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PREFACE 



This publication contains descriptions and definitions for the data management macro 
instructions, other than those of VSAM (virtual storage access method), available in the 
assembler language. It provides application and system programmers with the necessary 
information to code the macro instructions. 

This publication is divided into these parts: 

• "Introduction," which contains a general description of macro instructions, the rules 
to be followed when macro instructions are coded, and a description of the notational 
conventions used throughout the publication. 

• "Macro Instruction Descriptions," which describes the function of each macro 
instruction and defines how each macro instruction is to be coded. The macro 
instructions are presented in alphabetic order. The standard form of each macro 
instruction is described first, followed by the description of the list and execute form 
instructions; the list and execute forms are available only for those macro instructions 
that pass parameters in a list. 

• "Appendix A: Status Information Following an Input/Output Operation," which 
includes information about error indications available following an input/output 
operation. 

• "Appendix B: Data Management Macro Instructions Available by Access Method," 
which lists the macro instructions available for each of the data management access 
methods. 

• "Appendix C: Device Capacities," which lists device capacities that can be used as a 
guide when coding the block size and logical record length operands in the DCB 
macro instruction. 

• "Appendix D: DCB Exit List Format and Contents," which describes the format and 
content of the data control block exit list. 

• "Appendix E: Control Characters," which contains information about the control 
characters used to control spacing and skipping (printers) and stacker selection (card 
read punch or card punch). 

• "Appendix F: Data Control Block Symbolic Field Names," which lists the location, 
alignment, and description of the data control block symbolic field names. 

• "Appendix G: Event Control Block," which lists the location, alignment, and 
description of the event control block symbolic field names. 

• "Appendix H: PDABD Symbolic Field Names," which lists the location, alignment 
and description of the PDABD dummy control section. 

• "Index," which provides topic references to information in this book. 



Prerequisite Publications 



Before coding data management macro instructions, you should be familiar with the 
information in the following publications: 

. OS/VS—DOS/VS—VM/370 Assembler Language, GC33-4010 

• OS/VS2 MVS Data Management Services Guide, GC26-3875 

• OS/VS2 Supervisor Services and Macro Instructions, GC28-0683 
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Related Macro Instruction Publications 



The following publications contain descriptions of macro instructions for VSAM and for 
other specialized devices: 

• IBM 3800 Printing Subsystem Programmer's Guide, GC26-3846 

• IBM 3890 Document Processor Machine and Programming Description, 
GA24-3612 

• 05" Data Management Services and Macro Instructions for IBM 
1285/1287/1288, GC21-5004 

• OS Data Management Services and Macro Instructions for IBM 1419/1275, 
GC21-5006 

• OS and OS/VS Programming Support for the IBM 3505 Card Reader and 
IBM 3525 Card Punch, GC2 1-5097 

. OS/VS BTAM, GC27-6980 

• OS/VS Graphic Programming Services (GPS) for IBM 2250 Display Unit, 
GC27-6971 

• OS/VS Graphic Programming Services (GPS) for IBM 2260 Display Station 
(Local Attachment), GC27-6972 

• OS/VS IBM 3886 Optical Character Reader Model 1 Reference, GC24-5101 

• OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications, GC26-3 819 

• OS/VS Virtual Storage Access Method (VSAM) Programmer's Guide, GC26-3838 



Related System Publications 



This book refers to other publications that contain additional information about the 
operating system. Depending on the requirements of the individual installation, an 
application or system programmer may need these publications to code programs for the 
data management access methods. 

• OS/VS Checkpoint/ Restart, GC26-3784 

• OS/VS Linkage Editor and Loader, GC26-3813 
. OS/VS Utilities, GC35-0005 

. OS/VS2 JCL, GC28-0692 

• OS/VS2 Supervisor Services and Macro Instructions, GC28-0683 

• OS/VS2 System Programming Library: Data Management, GC26-3830 

• OS/VS 2 System Programming Library: Debugging Handbook, Volume 1, 
GC28-0708 

• OS/VS2 System Programming Library: Debugging Handbook, Volume 2, 
GC28-0709 

• OS/VS2 System Programming Library: System Generation Reference, GC26-3792 
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SUMMARY OF AMENDMENTS 

OS/VS MVS Data Management Support for Mass 
Storage System (MSS) Extensions Program Product 

MSS Extensions program product is supported by specifying OPTCD=U in the DCB 
macro for BSAM and QSAM data sets. 

Sequential Access Method-Extended (SAM-E) Release 1 (5740-AM3) 

BPAM, BSAM, and QSAM support of direct access storage devices (except BSAM 
MACRF=WL, create BDAM data set) has been modified to internally use the 
EXCPVR interface to IOS. This modification includes the functions of the chained 
scheduling option (OPTCD=C) and the search-direct option (OPTCD=Z). These 
options, therefore, need not be requested and are ignored if they are requested. 

OS/VS2 MVS 3800 Printing Subsystem (VS2.03.810) 

The 3800 Printing Subsystem is supported with this Selectable Unit. 

The BURST operand has been added to the standard, list, and execute forms of the 
SETPRT macro. Also, return code X'3C has been added for the 3800. 

OS/VS2 MVS Data Management (VS2.03.808) 

This newsletter contains a change for the OPEN macro to support the EXTEND and 
OUTINX options. These options allow the user to change the disposition of a data set to 
MOD. In all other ways, EXTEND and OUTINX are equivalent to the OUTPUT and 
OUTIN options, respectively. 

These new options will allow users of SAM and ISAM to add records to the end of an 
existing data set even though DISP=OLD/NEW/MOD/SHR was specified. In the past, 
the only way to add records to the end of the data set was to specify DISP=MOD on the 
DD statement and OUTPUT on the OPEN macro or to specify INOUT on the OPEN 
macro and read to end-of-file or use the OPEN TYPE=J macro. 



Release 3.7 



The IBM 3350 Direct Access Storage and IBM 3344 Direct Access Storage Device are 
now supported under VS2. This information is provided for planning purposes only until 
the products become available. 



Release 3 

New Programming Support 

The IBM 3850 Mass Storage System (MSS) is supported with this release. The MSS 
virtual volumes are functionally equivalent to the 3330/3333 Disk Storage, Model 1. For 
information on MSS, see OS/VS Mass Storage System (MSS) Planning Guide, 
GC35-0011. MSS information is provided for planning purposes only until the system is 
available. 



Summary of Amendments 1 1 



Release 2 



New Devices 



Exchange buffering support was removed for VS2 because it can badly affect 
performance in a virtual system. If exchange buffering is specified, it will be ignored by 
the system and move mode will be used instead. Move mode is compatible with exchange 
buffering. 

Chained scheduling will now be supported by VS2 whether it is requested or not (except 
for printers and format-U input records). This support was changed to improve 
performance in a virtual system. Chained scheduling will not be used where it previously 
was not allowed. 

For QSAM, BUFNO will now default to 5 buffers instead of 2. 



Information for Release 2 is provided for planning purposes only until this system is 
released. 



The IBM 3330 Disk Storage (Model 11), IBM 3333 Disk Storage and Control 
(Model 11), and the IBM 3340 Disk Storage are supported with this release. 

The system also supports the 3420 for Models 4, 6, and 8. 

The IBM 3890 Document Processor and IBM 3886 Optical Character Reader are 
supported with this release. For information on changes to macro instructions for 
these devices, see IBM 3890 Document Processor Machine and Programming 
Description, GA24-3612, or OS/ VS IBM 3886 Optical Character Reader Model 1 
Reference, GC24-5101. 



Other Technical Changes 



Editorial Changes 



Reason and return codes are now returned in registers and 15, respectively, for 
BLDL, BSP, FIND, and STOW macro instructions. 

The PDAB and PDABD macro instructions have been added for QSAM parallel input 
processing. The GET macro instruction for QSAM has also been changed to handle 
parallel input processing. 

The FREE option for the CLOSE macro instruction has been added. 

Any task sharing a DCB (which it did not open) can now issue the RELEX macro 
instruction to release exclusive control of a data block. 

Chained scheduling is supported in a virtual address space. 



The WAIT macro instruction has been added. 

The direct-access device capacity tables in Appendix C have been revised. 

Two charts of machine code control characters for printers and card punches have 
been added to Appendix E. 

A new appendix has been added which describes the symbolic field names in the 
PDABD macro instruction (Appendix H). 
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INTRODUCTION 



Data Management Macro Instructions 



Coding Aids 

Bold Type 



A set of macro instructions is provided by IBM for communicating service requests to the 
data management access method routines. These macro instructions are available only 
when the assembler language is being used, and they are processed by the assembler 
program using macro definitions supplied by IBM and placed in the macro library when 
the operating system is generated. 

The processing of the macro instruction by the assembler program results in a macro 
expansion, generally consisting of executable instructions and data in the form of 
assembler-language statements. The data fields are the parameters to be passed to the 
access method routine; the executable instructions generally consist of a branch around 
the data fields, instructions to load registers, and either a branch instruction or supervisor 
call (SVC) to give control to the proper program. The exact macro expansion appears as 
a part of the assembler listing. 

A listing of a macro definition from SYS1.MACLIB (the library in which macro 
definitions are stored) can be obtained by using the utility program IEBPTPCH, which is 
described in OS/VS Utilities. 

Before macro instructions are coded using this publication, the user should be familiar 
with the information contained in OS/ VS2 MVS Data Management Services Guide. 

When programs that request supervisor services are being coded, the user should be 
familiar with the information contained in OS/VS2 Supervisor Services and Macro 
Instructions. 

When programs are being coded for more specialized applications such as teleprocessing, 
graphics, character recognition, or to use VSAM (virtual storage access method), the 
publication that describes the specific access method and/or device type should be used. 
Publications containing descriptions of the macro instructions for teleprocessing, 
graphics, character recognition devices, and VSAM are listed in the preface of this 
publication. 

The operation of some macro instructions depends on the options selected when the 
macro instruction is coded. For these macro instructions, either separate descriptions are 
provided or the differences are listed within a single description. If no differences are 
explicitly listed, none exist. The description of each macro instruction starts on a 
right-hand page; the descriptions that do not apply to the access methods being used can 
be removed. Appendix B provides a list of the macro instructions available for each 
access method. 



Bold type is used for elements that you must code exactly as they are shown. These 
elements consist of macro names, keywords, and these punctuation symbols: commas, 
parentheses, and equal signs. Examples: 

. DCB 

. CLOSE „„TYPE=T 

. MACRF=(PL,PTC) 

• SK,5 
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Italic Type 



Brackets 



OR Sign 



Braces 



Italic type is used for elements for which you code values that you choose, usually 
according to specifications and limits described for each parameter. Examples: 

• number 

• image-id 

• count 



Brackets, [ ], are used to enclose optional elements, which you may code or not code as 
you choose. Examples: 

• [length] 

. [MF=E] 



The OR sign, | , is used to separate alternative elements. Examples: 
. [,REREAD | ,LEAVE] 

. [length |'S'] 



Braces, { }, are used to enclose alternative elements for which you must choose exactly 
one element, but never more than one element and never no element. Alternative items 
are usually separated by OR signs. Examples: 

. BFTEK={S|E|A} 

• {K|D} 

. {address | S | 0} 

Sometimes, alternative elements — especially complicated alternatives — are grouped in a 
vertical stack of braces. Examples: 

. MACRF= {(R[C | P]) } 

KW[C|P|L])} 

{(R[C],W[C]) } 

. DEVD= {DA 

[ ,KEYLEN= absexp ] } 

{TA 

[,DEN={0|1|2|3|4}] 
[,TRTCH={C|E|ET|T}] } 

{PT 

[,CODE={A|B|C|F|I|N|T}]} 

In these examples, you must choose exactly one element — one line — from the stack of 
alternative elements. 
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Ellipses 



Underscoring 



Blank Symbol 



Ellipses, ..., indicate that elements may be repeated. 

Example: 

• ( dcbaddr,\{ options)], ...) 

Underscored elements indicate those alternative choices that are assumed if you don't 
make an explicit choice. Examples: 

. HIARCHY={0|1} 

. BFALN={F|D} 

The blank symbol, b, is used to indicate the absence of operands. Example: 



b 


PDABD 


b 



Comprehensive Example 

. MF=(E,bddress\(l)}) 



In this example, MF=(E, must be coded exactly as shown. Then, either address or (1) 
must be coded; the parentheses around the 1 are required. Finally, the closing 
parenthesis must be coded. Thus, MF=(E,(1)) might be coded. 

RECFM= {U[T][A I M] }• 

{V[B|S|T|BS|BT][A|M]} 

{D[B][A] } 

{F[B|S|T|BS|BT][A|M]} 

In this example, the first choice is among the four alternative elements (on four 
separate lines). Then, choices must be made within the major element chosen. 
Assuming that the major element beginning with F were chosen, you would code F; 
then you would choose one of B, S, T, BS, or BT if you liked; and, finally, you would 
choose one of A or M if you liked. Thus, FBTM or FA might be coded. 
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Macro Instruction Format 



Data management macro instructions are written in the assembler language and, as such, 
are subject to the rules contained in OS/VS — DOS/VS — VM/370 Assembler Language. 
Data management macro instructions, like all assembler language instructions, are 
written in the following format: 



Name 


Operation 


Operands 


Comments 


Symbol or 
blank 


Macro name 


None, one or more operands separated 
by commas 





The operands are used to specify services and options to be used and are written 
according to the following general rules: 

• If the selected operand is shown in bold capital letters (for example, MACRF=WL), 
code the operand exactly as shown. 

• If the selected operand is a character string in bold type (for example, if the type 
operand of a READ macro instruction is SF), code the operand exactly as shown. 

• If the operand is shown in italic lowercase letters (for example, deb address), 
substitute the indicated address, name, or value. 

• If the operand is a combination of bold capital letters and italic lowercase letters (for 
example, LRECL=absexp), code the capital letters and equal sign exactly as shown 
and substitute the appropriate address, name, or value for the italic lowercase letters. 

• Commas and parentheses are coded exactly as shown, except that the comma 
following the last operand coded should be omitted. The use of commas and 
parentheses is indicated by brackets and braces in the same manner as brackets and 
braces indicate the use of operands. 

• Several macro instructions contain the designation 'S\ This operand, when used, must 
have the apostrophe on both sides of the S. 

When substitution of a name, value, or address is required, the notation used to specify 
the operand depends on the operand being coded. The following shows two examples of 
the notations used to indicate how an operand can be coded: 

DDNAME=symbol 

In the above example, the only type of operand that can be coded is a valid 

assembler-language symbol. 

deb address — RX-Type Address, (2-12), or (1) 

In the above example, the operand that can be substituted can be an RX-type address, 

any of the general registers 2 through 1 2, or general register 1 . 

The following describes the meaning of each notation used to show how an operand can 
be coded: 

symbol 

When this notation is shown, the operand can be any valid assembler-language 

symbol. 

decimal digit 

When this notation is shown, the operand can be any decimal digit up to the maximum 

value allowed for the specific operand being described. 
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(2-12) 

When this notation is shown, the operand specified can be any of the general registers 
2 through 12. All registers as operands must be coded in parentheses; for example, if 
register 3 is coded, it is coded as (3). When one of the registers 2 through 12 is used, 
it can be coded as a decimal digit, symbol (equated to a decimal digit), or an 
expression that results in a value of 2 through 12. 

(1) 

When this notation is shown, general register 1 can be used as an operand. When used 
as an operand in a macro instruction, the register must be specified as the decimal 
digit 1 enclosed in parentheses as shown above. 

(0) 

When this notation is shown, general register can be used as an operand. When used 
as an operand in a macro instruction, the register must be specified as the decimal 
digit enclosed in parentheses as shown above. 

RX-Type Address 

When this notation is shown, the operand can be specified as any valid 
assembler-language RX-type address. The following shows examples of each valid 
RX-type address: 

Name Operation Operand 



ALPHAI 


L 


1,39(4,10) 


ALPHA2 


L 


REG1,39(4,TEN) 


BETA1 


L 


2,ZETA(4) 


BETA2 


L 


REG2,ZETA(REG4) 


GAMMA1 


L 


2,ZETA 


GAMMA2 


L 


REG2,ZETA 


GAMMA3 


L 


2,=F1000' 


LAMBDA1 


L 


3,20(,5) 



Both ALPHA instructions specify explicit addresses; REG1 and TEN are absolute 
symbols. Both BETA instructions specify implied addresses, and both use index 
registers. Indexing is omitted from the GAMMA instructions. GAMMA 1 and 
GAMMA2 specify implied addresses. The second operand of GAMMA3 is a literal. 
LAMBDA 1 specifies an explicit address with no indexing. 

A-Type Address 

When this notation is shown, the operand can be specified as any address that can be 
written as a valid assembler-language A-type address constant. An A-type address 
constant can be written as an absolute value, a relocatable symbol, or relocatable 
expression. Operands that require an A-type address are inserted into an A-type 
address constant during the macro expansion process. For more details about A-type 
address constants, refer to OS/VS — DOS/VS — VM/370 Assembler Language. 

absexp 

When this notation is shown, the operand can be an absolute value or expression. An 
absolute expression can be an absolute term or an arithmetic combination of absolute 
terms. An absolute term can be a nonrelocatable symbol, a self-defining term, or the 
length attribute reference. For more details about absolute expressions, refer to 
OS/VS— DOS/VS— VM/370 Assembler Language. 

relexp 

When this notation is shown, the operand can be a relocatable symbol or expression. 

A relocatable symbol or expression is one whose value changes by n if the program in 

which it appears is relocated n bytes away from its originally assigned area of storage. 

For more details about relocatable symbols and expressions, refer to 

OS/VS— DOS/VS— VM/370 Assembler Language. 
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Rules for Register Usage 



Many macro instruction expansions include instructions that use a base register 
previously defined by a USING statement. The USING statement must establish 
addressability so that macro expansion can include a branch around the in line parameter 
list, if present, and refer to data fields and addresses specified in the macro instruction 
operands. 

Macro instructions that use a BAL or BALR instruction to pass control to an access 
method routine, normally require that register 13 contain the address of an 18-word 
register-save area. The READ, WRITE, CHECK, GET, and PUT macro instructions are 
of this type. 

Macro instructions that use a supervisor call (SVC) instruction to pass control to an 
access method routine may modify general registers 0, 1, 14, and 15 without restoring 
them. Unless otherwise specified in the macro instruction description, the contents of 
these registers are undefined when the system returns control to the problem program. 

When an operand is specified as a register, the problem program must have inserted the 
value or address to be used into the register as follows: 

• If the register is to contain a value, it must be placed in the low-order portion of the 
register unless the macro instruction description states otherwise. Any unused bits in 
the register should be set to zero. 

• If the register is to contain an address, the address must be placed in the low-order 
three bytes of the register, and the high-order byte of the register should be set to 
zero. 

Note that if the macro instruction accepts the RX-type address, the high-order byte of a 
register can be efficiently cleared by coding the parameter as (reg) rather than just 
(reg). Then the macro instruction expands as: 

LA parmreg,0( reg ) by macro 

rather than: 

LA reg, 0( reg) by user 

and 

LR parmreg,reg by macro 



Rules for Continuation Lines 



The operand field of a macro instruction can be continued on one or more additional 
lines as follows: 

1 . Enter a continuation character (not blank, and not part of the operand coding) in 
column 72 of the line. 

2. Continue the operand field on the next line, starting in column 1 6. All columns to the 
left of column 16 must be blank. 
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The operand field being continued can be coded in one of two ways. The operand field 
can be coded through column 71, with no blanks, and continued in column 16 of the next 
line, or the operand field can be truncated by a comma, where a comma normally falls, 
with at least one blank before column 71, and then continued in column 16 of the next 
line. An example of each method is shown in the following illustration: 

Name Operation Operand Comments 

NAME 1 OP 1 OPERAND 1 , OPERAND2 , OPERAND3 , OPERAND4 , OPERAND5 , OPERAND6 , OPERAND7 , OPEX 
RAND8 THIS IS ONE WAY 

NAME2 OP2 OPERANDI ,OPERAND2, THIS IS ANOTHER WAY X 

OPERAND3, X 

OPERAND4 
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MACRO INSTRUCTION DESCRIPTIONS 



BLDL — Build a Directory Entry List (BPAM) 



The BLDL macro instruction is used to complete a list of information from the directory 
of a partitioned data set. The problem program must supply a storage area; the area must 
include information about the number of entries in the list, the length of each entry, and 
the name of each data set member (or alias) before the BLDL macro instruction is 
issued. Data set member names in the list must be in alphameric order. All read and write 
operations using the same data control block must have been tested for completion 
before the BLDL macro instruction is issued. 

The BLDL macro instruction is written as follows: 



[symbol] 


BLDL 


deb address 
ylist address 



deb address — RX-type Address, (2-12), (1), or the decimal digit 

The deb address operand specifies the address of the data control block for an open 
partitioned data set, or zero can be specified to indicate that the data set is in a job 
library, step library, or link library. 

list address — RX-Type Address, (2-12), or (0) 

The list address operand specifies the address of the list to be completed when the 
BLDL macro instruction is issued. The list address must be on a halfword boundary. 
The following illustration shows the format of the list: 

List or 

List Description List More 

Address-, Field Entry (LL bytes) Entries (FF total) 



FF 



LL 



Length 

(bytes) 2 2 



NAME1 



TTR 



USER DATA 



NAME 2 



3 111 



0to62 



FF: This field must contain a binary value indicating the total number of entries in the 
list. 

LL: This field must contain a binary value indicating the length, in bytes, of each entry 
in the list (must be an even number of bytes). If the exact length of the entry is 
known, specify the exact length. Otherwise, specify at least 58 bytes (decimal) if the 
list is to be used with an ATTACH, LINK, LOAD, or XCTL macro instruction. The 
minimum length for a list is 12 bytes. 

NAME: This field must contain the member name or alias to be located. The name 
must start in the first byte of the name field and be padded to the right with blanks 
(if necessary) to fill the 8-byte field. 

When the BLDL macro instruction is executed, five fields of the directory entry list 
are filled in by the system. The specified length (LL) must be at least 14 to fill in the Z 
and C fields. If the LL field is 12, only the NAME, TT, R, and K fields are returned. 
The five fields are: 

TT: Indicates the relative track number where the beginning of the data set member is 
located. 

R: Indicates the relative block (record) number on the track indicated by TT. 
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K: Indicates the concatenation number of the data set. For the first or only data set, 
this value is zero. 

Z: Indicates where the system found the directory entry: 
Code Meaning 

Private library 

1 Link library 

2 Job, task, or step library 

3-255 Job, task, or step library of parent task n, where n = Z-2 

C: Indicates the type (member or alias) for the name, the number of note list fields 
(TTRNs), and the length of the user data field (indicated in halfwords). The following 
describes the meaning of the eight bits: 

Bit Meaning 

0=0 Indicates a member name. 

0=1 Indicates an alias. 

1-2 Indicate the number of TTRN fields (maximum of three) in the user data field. 

3-7 Indicate the total number of halfwords in the user data field. If the list entry is to be used 

with an ATTACH, LINK, LOAD, or XCTL macro instruction, the value in bits 3 

through 7 is 22 (decimal). 

USER DATA: The user data field contains the user data from the directory entry. If 
the length of the user data field in the BLDL list is equal to or greater than the user 
data field of the directory entry, the entire user data field is entered into the list. 
Otherwise, the list contains only the user data for which there is space. 



Completion Codes 



When the system returns control to the problem program, the low-order byte of register 
15 contains a return code; the low-order byte of register contains a reason code, as 
follows: 

Hexadecimal Codes 
Return (15) Reason (0) Meaning 

00 00 Successful completion. 

04 00 One or more entries in the list could not be filled; the list supplied may be 

invalid. If a search is attempted but the entry is not found, the R field (byte 

1 1 ) for that entry is set to zero. 
08 00 A permanent I/O error was detected when the system attempted to search 

the directory. 
08 04 Insufficient virtual storage was available. 
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BSP — Backspace a Physical Record (BSAM — Magnetic 
Tape and Direct Access Only) 

The BSP macro instruction causes the current volume to be backspaced one data block 
(physical record). All input and output operations must be tested for completion before 
the BSP macro instruction is issued. The BSP macro instruction should not be used if the 
CNTRL, NOTE, or POINT macro instructions are being used. The BSP macro can be 
used only on BSAM-created data sets. 

Any attempt to backspace across a file mark will result in a return code of X'04' and 
your tape or direct-access volume will not be repositioned. This means you cannot issue a 
successful BSP macro instruction once your EODAD routine is entered unless you first 
reposition the tape or direct-access volume into your data set. (CLOSE TYPE=T would 
get you repositioned at the end of your data set.) 

Magnetic Tape: A backspace is always made toward the load point. 

Direct-Access Device: A BSP macro instruction must not be issued for a data set created 
by using track overflow. 

SYSIN or SYSOUT Data Sets: A BSP macro instruction is ignored, but a completion 
code is returned. 

The BSP macro instruction is written as follows: 



[symbol] 


BSP 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
volume to be backspaced. The data set on the volume to be backspaced must be 
opened before issuing the BSP macro instruction. 



Completion Codes 



When the system returns control to the problem program, the low-order byte of register 
15 contains a return code; the lower-order byte of register contains a reason code, as 
follows: 

Hexadecimal Codes 
Return (15) Reason (0) Meaning 

Successful completion. 

A backspacing request was ignored on a SYSIN or SYSOUT data set. 

Backspace not supported for this device type. 

Backspace not successful; insufficient virtual storage was available. 

Backspace not successful; permanent I/O error. 

Backspace into load point or beyond start of data set on the current volume. 



00 


00 


04 


01 


04 


02 


04 


03 


04 


04 


04 


05 



Macro Instruction Descriptions 23 



BUILD— Build a Buffer Pool (BDAM, BISAM, BPAM, 
BSAM, QISAM, and QSAM) 

The BUILD macro instruction is used to construct a buffer pool in an area provided by 
the problem program. The buffer pool may be used by more than one data set through 
separate data control blocks. Individual buffers are obtained from the buffer pool using 
the GETBUF macro instruction, and buffers are returned to the buffer pool using a 
FREEBUF macro instruction. Refer to OS/VS2 MVS Data Management Services 
Guide for an explanation of the interaction of the DCB, BUILD, and GETBUF macro 
instructions in each access method, as well as the buffer size requirements. 

The BUILD macro instruction is written as follows: 



[symbol] 


BUILD 


area address 

A number of buffers , buffer length | (0)} 



area address — RX-Type Address, (2-12), or (1) 

The area address operand specifies the address of the area to be used as a buffer 
pool. The area must start on a fullword boundary. The following illustration shows the 
format of the buffer pool: 



Area 
Address 



Buffer Pool 

Control 

Block 



8 bytes 



Buffer 



Buffer 
Length 



Buffer 



Buffer 
Length 



Area Length 



Area Length=(Buffer Length) x (Number of Buffers) +8 

number of buffers — symbol, decimal digit, absexp, or (2-12) 

The number-of-buffers operand specifies the number of buffers in the buffer pool up 
to a maximum of 255. 

buffer length — symbol, decimal digit, absexp, or (2-12) 

The buffer length operand specifies the length, in bytes, of each buffer in the buffer 
pool. The value specified for the buffer length must be a fullword multiple; otherwise 
the system rounds the value specified to the next higher fullword multiple. The 
maximum length that can be specified is 32,760 bytes. For QSAM, the buffer length 
must be at least as large as the value specified in the block size (DCBBLKSI) field of 
the data control block. 
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BUILD 

(0) — Coded as shown 

The number of buffers and buffer length can be specified in general register 0. If (0) 
is coded, register must contain the binary values for the number of buffers and 
buffer length as shown in the following illustration. 



Bits: 



Register 












Number of Buffers 


Buffer Length 







15 


16 




31 
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BUILDRCD — Build a Buffer Pool and a Record Area 
(QSAM) 

The BUILDRCD macro instruction causes a buffer pool and a record area to be 
constructed in a user-provided storage area. This macro is used only for variable-length, 
spanned records processed in QSAM locate mode. Use of this macro before the data set 
is opened, or before the end of the DCB open exit routine, will provide a buffer pool that 
can be used for a logical record interface rather than a segment interface for 
variable-length spanned records. To invoke a logical record interface, specify BFTEK=A 
in the DCB. The BUILDRCD macro cannot be specified when logical records exceed 
32,760 bytes. 

The standard form of the BUILDRCD macro instruction is written as follows (the list 
and execute forms are shown following the description of the standard form): 



[symbol] 


BUILDRCD 


area address 

, number of buffers 

, buffer length 

, record area address 

[, record area length ] 



area address — A-Type Address or (2-12) 

The area address operand specifies the address of the area to be used as a buffer 
pool. The area must start on a fullword boundary. 

number of buffers — symbol, decimal digit, absexp, or (2-12) 

The number of buffers operand specifies the number of buffers, up to a maximum of 
255, to be in the buffer pool. 

buffer length — symbol, decimal digit, absexp, or (2-12) 

The buffer length operand specifies the length, in bytes, of each buffer in the buffer 
pool. The value specified for the buffer length must be a fullword multiple; otherwise, 
the system rounds the value specified to the next higher fullword multiple. The 
maximum length that can be specified is 32,760. 

record area address — A-Type Address or (2-12) 

The record area address operand specifies the address of the storage area to be used 
as a record area. The area must start on a doubleword boundary and have a length of 
the maximum logical record (LRECL) plus 32 bytes. 

record area length — symbol, decimal digit, absexp, or (2-12) 

The record area length operand specifies the length of the record area to be used. 
The area must be as long as the maximum length logical record plus 32 bytes for 
control information. If the record area length operand is omitted, the problem 
program must store the record area length in the first four bytes of the record area. 
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BUILDRCD— QSAM 



The following illustration shows the format of the buffer pool: 



Area 
Address 



BUFAD 



Address of First 
Available Buffer 



BUFLG 



Flags 



BUFNO 



No. of 
Buffers 
Req'd 



BUFLTH 



Length of 

Each 

Buffer 



BUFRECAD 



Address 
of Record 
Area 



Buffer 



Buffer 



4 bytes 



1 byte 1 byte 2 bytes 
1 2 bytes 



4 bytes 



Buffer 



Buffer Pool Control Block 



Length 



Area Length 



Buffer 



Length 



Area Length = (Buffer Length) x (Number of Buffers) +12 

BUFLG Flags: 
Bit Meaning 

0= 1 Record area present 

I = I Buffer control block extended 

2-7 Reserved 

Notes: 

• The buffer control block contains the address of the record area and a flag that 
indicates logical-record interface processing of variable-length, spanned records. 

• It is the user's responsibility to release the buffer pool and the record area after a 
CLOSE macro instruction has been issued for all the data control blocks using the 
buffer pool and the record area. 
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BUILDRCD— List Form 



The list form of the BUILDRCD macro instruction is used to construct a program 
parameter list. The description of the standard form of the BUILDRCD macro 
instruction provides the explanation of the function of each operand. The description of 
the standard form also indicates which operands are totally optional and those required 
in at least one of the pair of list and execute forms. The format description below 
indicates the optional and required operands in the list form only. 

The list form of the BUILDRCD macro instruction is written as follows: 



[ symbol ] 


BUILDRCD 


area address 

, number of buffers 

, buffer length 

, record area address 

[, record area length ] 

,MF=L 



area address — A-Type Address 

number of buffers — symbol, decimal digit, or absexp 

buffer length — symbol, decimal digit, or absexp 

record area address — A-Type Address 

record area length — symbol, decimal digit, or absexp 

MF=L — Coded as shown 

The MF=L operand specifies that the BUILDRCD macro instruction is used to create 
a control program parameter list, that will be referenced by an execute form 
instruction. 

Note: A control program parameter list can be constructed by coding only the MF=L 
operand (without the preceding comma); in this case, the list is constructed for the area 
address, number of buffers, buffer length, and record area address operands. If the 
record area length operand is also required, the operands can be coded as follows: 

[symbol] BUILDRCD „„0,MF=L 

The preceding example shows the coding to construct a list containing address constants 
with a value of in each constant. The actual values can then be supplied by the execute 
form of the BUILDRCD macro instruction. 
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BUILDRCD — Execute Form 



A remote control program parameter list is referred to, and can be modified by, the 
execute form of the BUILDRCD macro instruction. The description of the standard form 
of the BUILDRCD macro instruction provides the explanation of the function of each 
operand. The description of the standard form also indicates which operands are totally 
optional and those required in at least one of the pair of list and execute forms. The 
format description below indicates the optional and required operands for the execute 
form only. 

The execute form of the BUILDRCD macro instruction is written as follows: 



[symbol] 


BUILDRCD 


[area address] 

.[number of buffers] 

.[buffer length] 

,[ record area address] 

.[record area length] 

,MF=(E,{ control program list address 1(1)}) 



area address — RX-Type Address or (2-12) 

number of buffers — absexp 

buffer length — absexp 

record area address — RX-Type Address or (2-12) 

record area length — absexp 

MF=(E, control program list address | (1)}) 

This operand specifies that the execute form of the BUILDRCD macro instruction is 
used, and an existing control program parameter list (created by a list-form 
instruction) will be used. The MF= operand is coded as described in the following: 

E — Coded as shown 

control program list address — RX-Type Address, (2-12), or (1) 
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CHECK — Wait for and Test Completion of a Read or 
Write Operation (BDAM, BISAM, BPAM, and BSAM) 

The CHECK macro instruction causes the active task to be placed in the wait condition, 
if necessary, until the associated input or output operation is completed. The input or 
output operation is then tested for errors and exceptional conditions. If the operation is 
completed successfully, control is returned to the instruction following the CHECK 
macro instruction. If the operation is not completed successfully, the error analysis 
(SYNAD) routine is given control or, if no error analysis routine is provided, the task is 
abnormally terminated. The error analysis routine is discussed in the SYNAD operand of 
the DCB macro instruction. 

The following conditions are also handled for BPAM and BSAM only: 

When Reading: The end-of-data (EODAD) routine is given control if an input request is 
made after all the records have been retrieved. Volume switching is automatic for a 
BSAM data set that is not opened for UPDAT. For a BSAM data set that is opened for 
update, the end-of-data routine is entered at the end of each volume. 

When Writing: Additional space on the device is obtained when the current space is filled 
and more WRITE macro instructions have been issued. 

For BPAM and BSAM, a CHECK macro instruction must be issued for each input and 
output operation, and must be issued in the same order as the READ or WRITE macro 
instructions were issued for the data set. For BDAM or BISAM, either a CHECK or 
WAIT macro instruction can be used. For information on when the WAIT macro can be 
used, see OS/VS2 MVS Data Management Services Guide. 

If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. If translation is requested, the Check routine 
automatically translates BSAM records, as they are read, from ASCII code to EBCDIC 
code, provided that the record format is F, FB, D, DB, or U. Translation occurs as soon 
as the Check routine determines that the input buffer is full. For translation to occur 
correctly, all input data must be in ASCII code. 

The CHECK macro instruction is written as follows: 



[symbol] 


CHECK 


decb address 
[,DSORG={IS|ALL}] 



decb address — RX-Type Address, (2-12), or (1) 

The decb address operand specifies the address of the data event control block 
created by the associated READ or WRITE macro instruction or used by the 
associated input or output operation. 

DSORG={IS|ALL} 

The DSORG operand specifies the type of data set organization. The following 
describes the characters that can be coded: 

IS 

Specifies that the program generated is for BISAM use only. 

ALL 

Specifies that the program generated is for BDAM, BISAM, BPAM, or BSAM use. 

If the DSORG operand is omitted, the program generated is for BDAM, BPAM, or 
BSAM use only. 



30 OS/VS2 Data Management Macro Instructions 



CHKPT — Take a Checkpoint for Restart Within a Job 
Step (BDAM, BISAM, BPAM, BSAM, QISAM, and 
QSAM) 

The CHKPT macro instruction establishes a checkpoint for the job step. If the step 
terminates abnormally, it is automatically restarted from the checkpoint. On restart, 
execution resumes with the instruction that follows the CHKPT instruction. If the step 
again terminates abnormally (before taking another checkpoint), it is again restarted 
from the checkpoint. When several checkpoints are taken, the step is automatically 
restarted from the most recent checkpoint. 

Automatic restart from a checkpoint is suppressed if: 

1. The job step completion code is not one of a set of codes specified at system 
generation. 

2. The operator does not authorize the restart. 

3. The restart definition parameter of the JOB or EXEC statement specifies no restart 
(RD=NR) or no checkpoint (RD=NC or RD=RNC). 

4. The CANCEL operand appears in the last CHKPT macro instruction issued before 
abnormal termination. 

Under any of these conditions, automatic checkpoint restart does not occur. Automatic 
step restart (restart from the beginning of the job step) can occur, except under 
condition 1 or 2, or when the job step was restarted from a checkpoint prior to abnormal 
termination. Automatic step restart is requested through the restart definition parameter 
of the JOB or EXEC statement (RD=R or RD=RNC). 

When automatic restart is suppressed or unsuccessful, a deferred restart can be requested 
by submitting a new job. The new job can specify restart from the beginning of the job 
step or from any checkpoint for which there is an entry in the checkpoint data set. 

The checkpoint data set contains the information necessary to restart the job step from a 
checkpoint. The control program records this information when the CHKPT macro 
instruction is issued. The macro refers to the data control block for the data set, which 
must be on a magnetic tape or direct-access volume. A tape can have standard labels, 
nonstandard labels, or no labels. 

If the checkpoint data set is not open when CHKPT is issued, the control program opens 
the data set and then closes it after writing the checkpoint entry. If the data set is 
physically sequential and is opened by the control program, the checkpoint entry is 
written over the previous entry in the data set, unless the DD statement specifies 
DISP=MOD. By writing entries alternately into two checkpoint data sets, it is possible to 
keep the entries for the two most recent checkpoints while deleting those for earlier 
checkpoints. 

The data control block for the checkpoint data set must specify: 

DSORG=PS or PO, RECFM=U or UT, MACRF=(W), BLKSIZE= nnn, and 
DDNAME= any name 

where nnn is at least 600 bytes, but not more than 32,760 bytes for magnetic tape and 
not more than the track length for direct access. (If the data set is opened by the control 
program, block size need not be specified; the device-determined maximum block size is 
assumed if no block size is specified.) For seven-track tape, the data control block must 
specify TRTCH=C; for direct access, it must specify or imply KEYLEN=0. To request 
chained scheduling, OPTCD=C and NCP=2 must be specified. With direct access, 
OPTCD=W can be specified to request validity checking for write operations, and 
OPTCD=WC can be specified to combine validity checking and chained scheduling. 
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The standard form of the CHKPT macro instruction is written as follows (information 
about the list and execute forms follows this description) : 



[symbol] 


CHKPT 


{ dcbaddr [, checkid addr [, checkid length | ,'S']] } 
{CANCEL } 



dcbaddr 

The deb address operand specifies the address of the data control block for the 
checkpoint data set. 

checkid address 

The checkid address operand specifies the address of the checkpoint identification 
field. The contents of the field are used when the job step is to be restarted from the 
checkpoint. They are used by the control program in requesting operator authorization 
for automatic restart. You can use it for requesting deferred restart. 

If the next operand specifies the length of the field {checkid length), or if it is omitted 
to imply a length of eight bytes, the field must contain the checkpoint identification 
when the CHKPT macro instruction is issued. If the next operand is written as *S', the 
identification is generated and placed in the field by the control program. If both 
operands are omitted, the control program generates the identification, but does not 
make it available to the problem program. In each case, the identification is written in 
a message to the operator. 

The control program writes the checkpoint identification as part of the entry in the 
checkpoint data set. For a sequential data set, the identification can be any 
combination of up to 16 letters, digits, printable special characters, and blanks. For a 
partitioned data set, it must be a valid member name of up to 8 letters and digits, 
starting with a letter. The identification for each checkpoint should be unique. 

If the control program generates the identification, the identification is 8 bytes in 
length. It consists of the letter C followed by a 7-digit decimal number. The number is 
the total number of checkpoints taken by the job, including the current checkpoint, 
checkpoints taken earlier in the job step, and checkpoints taken by any previous job 
steps. 

checkid length 

The checkid length operand specifies the length in bytes of the checkpoint 
identification field. The maximum length is 16 bytes if the checkpoint data set is 
physically sequential, 8 bytes if it is partitioned. For a partitioned data set, the field 
can be longer than the actual identification, if the unused portion is blank. If the 
operand is omitted, the implied length is 8 bytes. 

If you code 'S' the control program supplies the checkpoint identification. The implied 
field length is 8 bytes. 

CANCEL 

The CANCEL operand cancels the request for automatic restart from the most recent 
checkpoint. If another checkpoint is taken before abnormal termination, the job step 
can be restarted at that checkpoint. 
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CHKPT 

When control is returned, register 15 contains one of the following return codes: 

Hexadecimal Meaning 
Code 

00 Successful completion. Code 00 is also returned if the RD parameter was coded as 

RD=NC or RD=RNC to totally suppress the function of CHKPT. 

04 Restart has occurred at the checkpoint taken by the CHKPT macro instruction during the 

original execution of the job. A request for another restart of the same checkpoint is 
normally in effect. If a deferred restart was performed and RD=NC, NR, or RNC was 
specified in the resubmitted deck, a request for another restart is not in effect. 

08 Unsuccessful completion. A checkpoint entry was not written, and a restart from this 

checkpoint was not requested. A request for an automatic restart from a previous 
checkpoint remains in effect. 

One of the following conditions exists: 

• The parameters passed by the CHKPT macro instruction are invalid. 

• The CHKPT macro instruction was executed in an exit routine other than the 
end-of-volume exit routine. 

• A STIMER macro instruction has been issued, and the time interval has not been 
completed. 

• A WTOR macro instruction has been issued, and the reply has not been received. 

• The checkpoint data set is on a direct-access volume and is full. Secondary space 
allocation was requested and performed. (Secondary space allocation is performed for 
a checkpoint data set, but the allocated space is not used. However, had secondary 
allocation not been requested, the job step would have been abnormally terminated.) 

• A graphics-type DSORG has been found in an open DCB. Graphic devices are not 
supported in checkpoint/restart. 

• The job step contains more than one task. 

0C Unsuccessful completion. An uncorrectable error occurred in writing the checkpoint entry 

or in completing queued access method input/output operations that were begun before 
the CHKPT macro instruction was issued. A partial, invalid checkpoint entry may have 
been written. If the entry has a programmer-specified checkid, and the checkpoint data 
set is sequential, a different checkid should be specified the next time CHKPT is executed. 
If the data set is partitioned, a different checkid need not be specified. This code is also 
returned if the checkpoint routine tries to open the checkpoint data set and the DD 
statement for the data set is missing. 

10 Successful completion with possible error condition. The task has control, by means of an 

explicit or implied use of the ENQ macro instruction, of a serially reusable resource; if the 
task terminates abnormally, it will not have control of the resource when the job step is 
restarted. The user's program must, therefore, reissue the ENQ macro instruction. 

14 Checkpoint not taken. End of volume occurred while writing the checkpoint entry on a 

tape data set. The checkpoint was canceled, but processing of the user's program 
continues. 

When one of the errors indicated by code 08, 0C, 10, or 14 occurs, the system prints an 
error message on the operator's console. The message indicating code 08 or 0C contains 
a code that further identifies the error. The operator should report the message contents 
to the programmer. 

Note: Successful use of the CHKPT macro instruction requires some care in the selection 
of checkpoints. For a detailed discussion of checkpoint requirements, refer to OS/VS 
Checkpoint /Restart. 
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CHKPT— List Form 



The list form of the CHKPT instruction is used to construct a control program parameter 
list. 

The description of the standard form of the CHKPT macro provides the explanation of 
the function of each operand. The description of the standard form also indicates which 
operands are optional and which are required in at least one of the list and execute 
forms. The format description below indicates the optional and required operands in the 
list form only. Note that the CANCEL operand, which can be coded in the standard 
form, cannot be coded in the list form. 

The list form of the CHKPT macro instruction is written as follows: 



[symbol] 


CHKPT 


[deb address] 
,[checkid address] 
,[checkid length | 'S'] 
,MF=L 



address 

The address operand specifies any address that may be written in an A-type address 
constant. 

length 

The length operand specifies any absolute expression that is valid in the assembler 
language. 

MF=L 

The MF=L operand indicates the list form of the CHKPT macro instruction. 
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CHKPT — Execute Form 



A control program parameter list is referred to, and can be modified by, the execute form 
of the CHKPT macro. 

The description of the standard form of the CHKPT macro provides the explanation of 
the function of each operand. The description of the standard form also indicates which 
operands are optional and which are required in at least one of the list and execute 
forms. The format description below indicates the optional and required operands for the 
execute form only. Note that the CANCEL operand, which can be coded in the standard 
form, cannot be coded in the execute form. 

The execute form of the CHKPT macro instruction is written as follows: 



[symbol] 


CHKPT 


[deb address] 

,[ check id address] 

,[ check id length | 'S'] 

,MF=(E,{ control program list address | (1)}) 



address 

The address operand specifies any address that is valid in an RX-type instruction, or 
one of the general registers 2 through 12, previously loaded with the indicated 
address. You may designate the register symbolically or with an absolute expression; 
always code it in parentheses. 

length 

The length operand specifies any absolute expression that is valid in assembler 
language, or one of the general registers 2 through 12, previously loaded with the 
indicated value. You may designate the register symbolically or with an absolute 
expression; always code it in parentheses. 

MF=(E,{ control program list address | (1)}) 

This operand specifies the execute form of the macro instruction using a control 
program parameter list. The address of the control program parameter list can be 
coded as described under address, or can be loaded into register 1, in which case code 
MF=(E,(1)). 
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CLOSE — Logically Disconnect a Data Set (BDAM, 
BISAM, BPAM, BSAM, QISAM, and QSAM) 

The CLOSE macro instruction causes output data set labels to be created, and volumes 
to be positioned as specified by the user. The fields of the data control block are restored 
to the condition that existed before the OPEN macro instruction was issued, and the data 
set is disconnected from the processing program. Final volume positioning for the current 
volume can be specified to override the positioning implied by the DD control statement 
DISP parameter. Any number of deb address operands and associated options may be 
specified in the CLOSE macro instruction. 

Associated data sets for a 3525 card punch can be closed in any sequence, but if one 
data set is closed, I/O operations cannot be initiated for any of its associated data sets. 
Additional information about closing associated data sets is contained in OS/VS2 MVS 
Data Management Services Guide. 

A FREEPOOL macro instruction should normally follow a CLOSE macro instruction 
(without TYPE=T) to regain the buffer pool storage space and to allow a new buffer 
pool to be built if the DCB is reopened with different record size attributes. 

A special operand, TYPE=T, is provided for processing with BSAM. 

The standard form of the CLOSE macro instruction is written as follows (the list and 
execute forms are shown following the description of the standard form): 



[symbol] 


CLOSE 


(deb address, [option ],...) 
[,TYPE=T] 



deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened data set that is to be closed. 

option 

One of these options indicates the volume positioning that is to occur when the data 
set is closed. This option has meaning only with the TYPE=T operand or for data sets 
on magnetic tape. The options are: 

REREAD 

Specifies that the current volume is to be positioned to reprocess the data set. If 
processing was forward, the volume is positioned to the beginning of the data set; if 
processing was backwards (RDBACK), the volume is positioned to the end of the 
data set. 

LEAVE 

Specifies that the current volume is to be positioned to the logical end of the data 
set. If processing was forward, the volume is positioned to the end of the data set; 
if processing was backwards (RDBACK), the volume is positioned to the beginning 
of the data set. 

REWIND 

Specifies that the current magnetic tape volume is to be positioned at the load 
point, regardless of the direction of processing. REWIND cannot be specified when 
TYPE=T is specified. If FREE= CLOSE has been coded on the DD statement 
associated with the data set being closed, coding the REWIND option will result in 
the data set being freed at the time it is closed rather than at the termination of the 
job step. 
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CLOSE 

FREE 

Specifies that the current data set is to be freed at the time the data set is closed, 
rather than at the time the job step is terminated. For tape data sets, this means 
that the volume is eligible for use by other tasks or to be demounted. Direct-access 
volumes may also be freed for use by other tasks. They may be freed for 
demounting if (1) no other data sets on the volume are open and (2) the volume is 
otherwise demountable. Do not use this option with CLOSE TYPE=T. 

DISP 

Specifies that a tape volume is to be disposed of in the manner implied by the DD 
statement associated with the data set. Direct-access volume positioning and 
disposition are not affected by this parameter of the CLOSE macro instruction. 
There are several dispositions that can be specified in the DISP parameter of the 
DD statement; DISP can be PASS, DELETE, KEEP, CATLG, or UNCATLG. 

Depending on how the DISP option is coded in the DD statement, the current 
magnetic tape volume will be positioned as follows: 

DISP Parameter Action 

PASS Forward space to the end of the data set on the current 

volume. 

DELETE Rewind the current volume. 

KEEP, CATLG, or UNCATLG The volume is positioned the same as for CLOSE 

REREAD. Note that the volume is not rewound and 
unloaded. 

If FREE= CLOSE has been coded in the DD statement associated with this data 
set, coding the DISP option in the CLOSE macro will result in the data set being 
freed when the data set is closed, rather than at the time the job step is terminated. 

Note: When the option operand is omitted, DISP is assumed. For TYPE=T, this is 
processed as LEAVE during execution. 

The LEAVE and REREAD options are meaningless except for magnetic tape and 
CLOSE TYPE=T. 

TYPE=T — Coded as shown 

You can code CLOSE TYPE=T to perform some close functions for sequential data 
sets on magnetic tape and direct-access volumes processed with BSAM. When you use 
TYPE=T, the DCB used to process the data set maintains its open status, and you 
should not issue another OPEN macro instruction to continue processing the same 
data set. This option cannot be used in a SYNAD routine nor can it be used in 
conjunction with the FREE option. 

The TYPE=T operand causes the system control program to process labels, modify 
some of the fields in the system control blocks for that data set, and reposition the 
volume (or current volume in the case of multivolume data sets) in much the same 
way that the normal CLOSE macro does. When you code TYPE=T, you can specify 
that the volume either be positioned at the end of data (the LEAVE option) or be 
repositioned at the beginning of data (the REREAD option). Magnetic-tape volumes 
are repositioned either immediately before the first data record or immediately after 
the last data record; the presence of tape labels has no effect on repositioning. 
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If you code the release (RLSE) operand on the DD statement for an output data set, 
it is ignored by temporary close (CLOSE TYPE=T), but any unused space will be 
released when you finally issue the normal CLOSE (without TYPE=T) macro 
instruction. 

Refer to OS/VS2 MVS Data Management Services Guide for additional 
information and coding restrictions. 
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CLOSE — List Form 



The list form of the CLOSE macro instruction is used to construct a data management 
parameter list. Any number of operands (data control block addresses and associated 
options) can be specified. 

The list consists of a one-word entry for each DCB in the parameter list; the high-order 
byte is used for the options and the three low-order bytes are used for the DCB address. 
The end of the list is indicated by a one in the high-order bit of the last entry's option 
byte. The length of a list generated by a list-form instruction must be equal to the 
maximum length required by an execute-form instruction that refers to the same list. A 
maximum length list can be constructed by one of two methods: 

• Code a list-form instruction with the maximum number of parameters that are 
required by an execute-form instruction that refers to the list. 

• Code a maximum length list by using commas in a list-form instruction to acquire a list 
of the appropriate size. For example, coding CLOSE (,„„„„), MF=L would provide a 
list of five fullwords (five deb addresses and five options). 

Entries at the end of the list that are not referenced by the execute-form instruction are 
assumed to have been filled in when the list was constructed or by a previous 
execute-form instruction. Before using the execute-form instruction, you may shorten the 
list by placing a one in the high-order bit of the last DCB entry to be processed. 

A zeroed work area on a word boundary is equivalent to CLOSE (,DISP,...),MF=L and 
can be used in place of a list- form instruction. The high-order bit of the last DCB entry 
must contain a one before this list can be used with the execute-form instruction. 

A parameter list constructed by a CLOSE macro instruction, list form, can be referred to 
by either an OPEN or CLOSE execute-form instruction. 

The description of the standard form of the CLOSE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are completely optional and those required in at least one of 
the pair of list and execute forms. The format description below indicates the optional 
and required operands in the list form only. 

The list form of the CLOSE macro instruction is written as follows: 



[symbol] 


CLOSE 


([ deb address ],[ option ],...) 

[,TYPE*=T] 

,MF=L 



deb address — A-Type Address 

option — Same as standard form 

TYPE=T — Coded as shown 

The TYPE=T operand can be coded in the list-form instruction to allow the specified 
option to be checked for validity when the program is assembled. 

MF=L — Coded as shown 

The MF»L operand specifies that the CLOSE macro instruction is used to create a 
data management parameter list that will be referred to by an execute-form 
instruction. 
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CLOSE — Execute Form 



A remote data management parameter list is used in and can be modified by the execute 
form of the CLOSE macro instruction. The parameter list can be generated by the list 
form of either an OPEN macro instruction or a CLOSE macro instruction. 

The description of the standard form of the CLOSE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands in the execute form only. 

The execute form of the CLOSE macro instruction is written as follows: 



[symbol] 



CLOSE 



{{[deb address \[option ], ...)] 

[,TYPE=T] 

,MF=(E,{ data management list address | (1)}) 



deb address — RX-Type Address or (2-12) 

option — If specified, same as the standard form. If not specified, the option specified in 
the remote data management parameter list will be used. 

TYPE=T — Same as standard form 

MF=(E,{ data management list address | (1)}) 

This operand specifies that the execute form of the CLOSE macro instruction is being 
used, and an existing data management parameter list (created by a list-form 
instruction) will be used. The MF= operand is coded as described in the following: 

E — Coded as shown 

data management list address — RX-Type Address, (2-12), or (1) 
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CNTRL— Control Online Input/Output Device (BSAM 
and QSAM) 

The CNTRL macro instruction is used to control magnetic tape drives (BSAM only for a 
data set that is not open for output), online card readers, 3525 card punches (read and 
print features, VS2 only), printers (BSAM and QSAM), the 3886 Optical Character 
Reader (BSAM only), and the 3890 Document Processor (QSAM only). For information 
on additional operands for the CNTRL macro instruction for the 3886 and 3890, see 
OS/ VS IBM 3886 Optical Character Reader Model I Reference and IBM 3890 
Document Processor Machine and Programming Description. 

For information on additional operands for the CNTRL macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275. 

The MACRF operand of the DCB macro instruction must specify a C. The CNTRL 
macro instruction is ignored for SYSIN or SYSOUT data sets. For BSAM, all input and 
output operations must be tested for completion before the CNTRL macro instruction is 
issued. The control facilities available are as follows: 

Card Reader: Provides stacker selection, as follows: 

QSAM — For unblocked records, a CNTRL macro instruction should be issued after 
every input request. For blocked records, a CNTRL macro instruction is issued after the 
last logical record on each card that is retrieved. Whether reading blocked or unblocked 
records, do not issue a CNTRL macro instruction after a GET macro has caused control 
to pass to the EODAD routine. The move mode of the GET macro instruction must be 
used, and the number of buffers (BUFNO field of the DCB) must be one. If a CLOSE 
macro instruction is issued before the last card is read, the operator should clear the 
reader before the device is used again. 

BSAM — The CNTRL macro instruction should be issued after every input request. 

Printer: Provides line spacing or a skip to a specific carriage control channel. A CNTRL 
macro instruction cannot be used if carriage control characters are provided in the 
record. If the printer contains the universal character set feature, data checks should be 
blocked (OPTCD=U should not appear in the data control block). 

Magnetic Tape: Provides method of forward spacing and backspacing (BSAM only for a 
data set that is not open for output). If OPTCD=H is indicated in the data control block, 
the CNTRL macro instruction can be used to perform record positioning on DOS tapes 
that contain embedded checkpoint records. Embedded checkpoint records encountered 
during the record positioning are bypassed and are not counted as blocks spaced over. 
OPTCD=H must be specified in a job control language DD statement. The CNTRL 
macro instruction cannot be used to backspace DOS 7-track tapes that are written in 
data convert mode that contain embedded checkpoint records (BSAM). 

Note: The CNTRL macro should not be used with output operations on BSAM tape data 
sets. 

3525 Printing: Provides line spacing or a skip to a specific printing line on the card. The 
card contains 25 printing lines; the odd numbered lines 1 through 23 correspond to the 
printer skip channels 1 through 12 (see the SK operand). For additional information 
about 3525 printing operations, refer to OS and OS/VS Programming Support for 
the IBM 3505 Card Reader and IBM 3525 Card Punch. 
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The CNTRL macro instruction is written as follows: 



[symbol] 


CNTRL 


deb address 

{,SS,{1|2} } 
{,SP,{1|2|3} } 
{ ,SK,{1 I 2 | ... | 11 | } 
{ ,BSM } 
{ ,FSM } 
{ ,BSR[,number of blocks] } 
{ ,FSR[,number of blocks] } 



deb address 

The deb address operand specifies the address of the data control block for the data 
set opened for the online device. 

SS,{1|2} 

The SS operand is coded as shown to indicate that the control function requested is 
stacker selection on a card reader; either 1 or 2 must be coded to indicate which 
stacker is to be selected. 

SP,{1|2|3} 

The SP operand is coded as shown to indicate that the control function requested is 
printer line spacing or 3525 card punch line spacing; either 1, 2, or 3 must be coded to 
indicate the number of spaces for each print line. 

SK,{1 121 ... | 11 | 

The SK operand is coded as shown to indicate that the control function requested is a 
skip operation on the printer or 3525 card punch, print feature; a number (1 through 
12) must be coded to indicate the channel or print line to which the skip is to be 
taken. 

BSM — Coded as shown 

The BSM operand indicates that the control function requested is to backspace the 
magnetic tape past a tapemark, then forward space over the tapemark. When this 
operand is specified, the DCBBLKCT field in the data control block is set to zero. 

FSM — -Coded as shown 

The FSM operand indicates that the control function requested is to forward space the 
magnetic tape over a tapemark, then backspace past the tapemark. When this operand 
is specified, the DCBBLKCT field in the data control block is set to zero. 

BSR — Coded as shown 

The BSR operand indicates that the control function requested is to backspace the 
magnetic tape the number of blocks indicated in the number-of-blocks operand. 

FSR — Coded as shown 

The FSR operand indicates that the control function requested is to forward space the 
magnetic tape the number of blocks indicated in the number-of-blocks operand. 

number of blocks — symbol, decimal digit, absexp, or (2-12) 

The number-of-blocks operand specifies the number of blocks to backspace (see 
BSR operand) or forward space (see FSR operand) the magnetic tape. The 
maximum value that can be specified is 32,767. If the number-of-blocks operand is 
omitted, one is assumed. 

If the forward space or backspace operation is not completed successfully, control is 
passed to the error analysis (SYNAD) routine; if no SYNAD routine is designated, the 
task is abnormally terminated. Register contents, when control is passed to the error 



42 OS/VS2 Data Management Macro Instructions 



CNTRL— BSAM and QSAM 

analysis routine, are shown in Appendix A. If a tapemark is encountered for BSR or 
FSR, control is returned to the processing program, and register 15 contains a count of 
the uncompleted forward spaces or backspaces. If the operation is completed normally, 
register 15 contains the value zero. 
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DCB — Construct a Data Control Block (BDAM) 

The data control block for a basic direct access method (BDAM) data set is constructed 
during assembly of the problem program. The DCB macro instruction must not be coded 
within the first 16 bytes of addressability for the control section (CSECT). The DSORG 
and MACRF operands must be coded in the DCB macro instruction, but the other 
operands can be supplied from other sources. Each of the BDAM DCB operand 
descriptions contains a heading, "Source." The information under this heading describes 
the sources from which an operand can be supplied to the data control block. 

Before a DCB macro instruction for a BDAM data set is coded, the following 
characteristics of direct data sets should be considered: 

• The problem program must synchronize I/O operations by issuing a CHECK or 
WAIT macro instruction to test for completion of read and write operations. 

• A BDAM data set is created using the basic sequential access method (BSAM). A 
special operand (MACRF=WL) specifies that BSAM is being used to create a BDAM 
data set. Operand descriptions for the BDAM DCB macro instruction include 
information about both creating and processing a BDAM data set. 

• Although a BDAM data set can contain blocked records, the problem program must 
perform all blocking and deblocking of records. BDAM provides only the capability to 
read or write a data block, but the data block can contain multiple logical records 
assembled by the problem program. 

• When a BDAM data set is being created, buffers can be acquired automatically, but 
buffer control must be provided by the problem program. The problem program must 
place data in the output buffer before issuing a WRITE macro instruction to write the 
data block. 

• When a BDAM data set is being processed, the problem program can control all 
buffering, or dynamic buffering can be specified in the DCB macro instruction and 
subsequently requested in a READ macro instruction. 

• The actual organization of a direct data set is determined by the programmer to meet 
the needs of the application. The data set can be processed by using one of the 
following addressing methods: 

• Actual device addresses (in the form MBBCCHHR). 

• Relative track addresses (in the form TTR). These addresses specify a track (and a 
record on the track) of the direct-access device relative to the beginning of the data 
set. 

• Relative block addresses can be used with fixed-length records. These addresses 
specify a data block relative to the beginning of the data set. 

For additional information about the characteristics of BDAM data sets, refer to 
OS/VS2 MVS Data Management Services Guide. 
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DCB— BDAM 



The DCB macro for BDAM is written as follows: 



[symbol] 


DCB 


[BFALN={F|D}] 
[BFTEK=R] 
[BLKSIZE= absexp] 
[BUFCB= relexp] 
[BUFL= absexp] 
[BUFNO= absexp] 
[DDNAME= symbol ]> 
DSORG={DA|DAU} 
[EXLST= relexp ] 
[KEYLEN= absexp] 
[LIMCT= absexp ] 

MACRF= {(R{K[I] 1 1}[X][S][C]) } 

{(W{A[K][I] | K[I] | I}[C]) } 

{(R{K[I] | I}[X][S][C],W{A[K][I] | K[I] | I}[C])} 

[OPTCD=[R | A][E][F][W]] 
[RECFM={U | V[S | BS] | F[T]}] 
[SYNAD= relexp ] 



'This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 

The following describes the DCB operands that can be specified for creating and 
processing a BDAM data set: 

BFALN={F|D} 

The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool. The BFALN operand can be specified when (1) BSAM is being used to create a 
BDAM data set and buffers are acquired automatically, (2) when an existing BDAM 
data set is being processed and dynamic buffering is requested, or (3) when the 
GETPOOL macro instruction is used to construct the buffer pool. If the BFALN 
operand is omitted, the system provides doubleword alignment for each buffer. The 
following describes the characters that can be specified: 

F 

Specifies that each buffer is aligned on a fullword boundary that is not also a 
doubleword boundary. 

D 

Specifies that each buffer is aligned on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide the area for the 
buffers and control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied from the same source. 

BFTEK =R 

The BFTEK operand specifies that the data set is being created for or contains 
variable-length spanned records. The BFTEK operand can be coded only when the 
record format is specified as RECFM= VS. 
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When variable-length spanned records are written, the data length can exceed the 
total capacity of a single track on the direct-access device being used, or it can exceed 
the remaining capacity on a given track. The system divides the data block into 
segments (if necessary), writes the first segment on a track, and writes the remaining 
segment(s) on the following track(s). 

When a variable-length spanned record is read, the system reads each segment and 
assembles a complete data block in the buffer designated in the area address operand 
of a READ macro instruction. 

Note: Variable-length spanned records can also be read using BSAM. When BSAM is 
used to read a BDAM variable-length spanned record, the record is read one segment 
at a time, and the problem program must assemble the segments into a complete data 
block. This operation is described in the section for the BSAM DCB macro 
instruction. 

Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 

BLKSlZE=absexp (maximum value is 32,760) 

The BLKSIZE operand specifies the length, in bytes, of each data block for 
fixed-length records, or it specifies the maximum length, in bytes, of each data block 
for variable-length or undefined-length records. If keys are used, the length of the key 
is not included in the value specified for the BLKSIZE operand. 

The actual value that can be specified in the BLKSIZE operand depends on the record 
format and the type of direct-access device being used. If the track-overflow feature is 
being used or if variable-length spanned records are being used, the value specified in 
the BLKSIZE operand can be up to the maximum. For all other record formats (F, V, 
VBS, and U), the maximum value that can be specified in the BLKSIZE operand is 
determined by the track capacity of a single track on the direct-access device being 
used. Device capacity for direct-access devices is described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/VS2 MVS Data Management Services Guide. 

Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

BUFCB=relexp 

The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. 

If the buffer pool is constructed automatically, dynamically, or by a GETPOOL macro 
instruction, the system places the address of the buffer pool control block into the 
data control block, and the BUFCB operand is not required. The BUFCB operand is 
not required if the problem program controls all buffering. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

■BUFL=absexp (maximum value is 32,760) 

The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffers are acquired automatically (create BDAM) or dynamically (existing 
BDAM). 

When buffers are acquired automatically (create BDAM), the BUFL operand is 
optional; if specified, the value must be at least as large as the sum of the values 
specified for the KEYLEN and BLKSIZE operands. If the BUFL operand is 
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DCB— BDAM 

omitted, the system constructs buffers with a length equal to the sum of the values 
specified in the KEYLEN and BLKSIZE operands. 

The BUFL operand must be specified when an existing BDAM data set is being 
processed and dynamic buffering is requested. Its value must be at least as large as the 
value specified for the BLKSIZE operand when the READ or WRITE macro 
instruction specifies a key address, or the value specified in the BUFL operand must 
be at least as large as the sum of the values specified in the KEYLEN and BLKSIZE 
operands if the READ and WRITE macro instructions specify 'S' for the key address. 

The BUFL operand can be omitted if the buffer pool is constructed by a BUILD or 
GETPOOL macro instruction or if the problem program controls all buffering. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BUFNO=absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers and/or segment work areas to 
be acquired by the system. 

If the buffer pool is constructed by a BUILD macro instruction or if buffers are 
acquired automatically when BSAM is used to create a BDAM data set, the number of 
buffers must be specified in the BUFNO operand. 

If dynamic buffering is requested when an existing BDAM data set is being processed, 
the BUFNO operand is optional; if omitted, the system acquires two buffers. 

If variable-length spanned records are being processed and dynamic buffering is 
requested, the system also acquires a segment work area for each buffer. If dynamic 
buffering is not requested, the system acquires the number of segment work areas 
specified in the BUFNO operand. If the BUFNO operand is omitted when 
variable-length spanned records are being processed and dynamic buffering is not 
requested, the system acquires two segment work areas. 

If the buffer pool is constructed by a GETPOOL macro instruction or if the problem 
program controls all buffering, the BUFNO operand can be omitted, unless it is 
required to acquire additional segment work areas for variable-length spanned records. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

DDNAME=symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 

Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 

DSORG={DA|DAU} 

The DSORG operand specifies the data set organization and if the data set contains 
any location-dependent information that would make it unmovable. For example, if 
actual device addresses are used to process a BDAM data set, the data set may be 
unmovable. The following describes the characters that can be specified: 

DA 

Specifies a direct organization data set. 
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DAU 

Specifies a direct organization data set that contains location-dependent 
information. 

When a BDAM data set is created, the basic sequential access method (BSAM) is 
used. The DSORG operand in the DCB macro instruction must be coded as 
DSORG=PS or PSU when the data set is created, and the DCB subparameter in the 
corresponding DD statement must be coded as DSORG=DA or DAU. This creates a 
data set with a data set label identifying it as a BDAM data set. 

Source: The DSORG operand must be specified in the DCB macro instruction. See 
the above comment about creating a BDAM data set. 

EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand must be specified if the problem program processes user labels during 
the Open or Close routine, if the data control block exit routine is used for additional 
processing, or if the DCB ABEND exit is used for ABEND condition analysis. 

Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit list processing, refer to OS/ VS2 
MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the exit is needed. 

KEYLEN=absexp (maximum value is 255) 

The KEYLEN operand specifies the length, in bytes, of all keys used in the data set. 
When keys are used, a key is associated with each data block in the data set. If the key 
length is not supplied by any source, no input or output requests that require a key can 
be specified in a READ or WRITE macro instruction. 

Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by an existing data set label. If 
KEYLEN=0 is specified in the DCB macro instruction, a special indicator is set in 
RECFM so that KEYLEN cannot be supplied from the DCB subparameter of a DD 
statement or data set label of an existing data set. KEYLEN=0 can be coded only in 
the DCB macro instruction and will be ignored if specified in the DD statement. 

LlMCT=absexp 

The LIMCT operand specifies the number of blocks or tracks to be searched when the 
extended search option (OPTCD=E) is requested. 

When the extended search option is requested and relative block addressing is used, 
the records must be fixed-length record format. The system converts the number of 
blocks specified in the LIMCT operand into the number of tracks required to contain 
the blocks, then proceeds in the manner described below for relative track addressing. 

When the extended search option is requested and relative track addressing is used (or 
the number of blocks has been converted to the number of tracks), the system 
searches for the block specified in a READ or WRITE macro instruction (type DK), 
or it searches for available space in which to add a block (WRITE macro instruction, 
type DA). The search is as follows: 

• The search begins at the track specified by the block address operand of a READ 
or WRITE macro instruction. 

• The search continues until the search is satisfied, the number of tracks specified in 
the LIMCT operand have been searched, or the entire data set has been searched. 
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If the search has not been satisfied when the last track of the data set is reached, 
the system continues the search by starting at the first track of the data set if the 
EOF marker is on the last track that was allocated to the data set. (This operation 
allows the number specified in the LIMCT operand to exceed the size of the data 
set, causing the entire data set to be searched.) You can insure that the EOF 
marker is on the last allocated track by determining the size of the data set and 
allocating space in blocks, or by allocating space in tracks and including the RLSE 
parameter on the SPACE operand of the DD statement (RLSE specifies that all 
unused tracks be returned to the system). 

The problem program can change the DCBLIMCT field in the data control block at 
any time, but if the extended search option is used, the DCBLIMCT field must not be 
zero when a READ or WRITE macro instruction is issued. 

If the extended search option is not requested, the system ignores the LIMCT 
operand, and the search for a data block is limited to a single track. 

Source: The LIMCT operand can be supplied in the DCB macro instruction, the DCB 
subparameter of a DD statement, or by the problem program before the count is 
required by a READ or WRITE macro instruction. 

MACRF= {(R{K[I] | I}[X][S][C]) } 

{(W{A[K][I]|K[I]|I}[C]) } 

{<R{K[I] | I}[X][S][C],W{A[K][I] | K[I] | I}[C]) } 
The MACRF operand specifies the type of macro instructions (READ, WRITE, 
CHECK, and WAIT) used when the data set is processed. The MACRF operand also 
specifies the type of search argument and BDAM functions used with the data set. 
When BSAM is used to create a BDAM data set, the BSAM operand MACRF=WL is 
specified. This special operand invokes the BSAM routine that can create a BDAM 
data set. The following describes the characters that can be specified for BDAM: 

A 

Specifies that data blocks are to be added to the data set. 

C 

Specifies that CHECK macro instructions are used to test for completion of read 
and write operations. If C is not specified, WAIT macro instructions must be used 
to test for completion of read and write operations. 

I 

Specifies that the search argument is to be the block identification portion of the 
data block. If relative addressing is used, the system converts the relative address to 
a full device address (MBBCCHHR) before the search. 

K 

Specifies that the search argument is to be the key portion of the data block. The 
location of the key to be used as a search argument is specified in a READ or 
WRITE macro instruction. 

R 

Specifies that READ macro instructions are used. READ macro instructions can be 
issued when the data set is opened for INPUT, OUTPUT, or UPDAT. 

S 

Specifies that dynamic buffering is requested by specifying 'S' in the area address 
operand of a READ or WRITE macro instruction. 
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w 

Specifies that WRITE macro instructions are used. WRITE macro instructions can 
be issued only when the data set is opened for OUTPUT or UPDAT. 

X 

Specifies that READ macro instructions request exclusive control of a data block. 
When exclusive control is requested, the data block must be released by a 
subsequent WRITE or RELEX macro instruction. 

Source: The MACRF operand must be supplied in the DCB macro instruction. 

OPTCD=[R | A][E][F][W] 

The OPTCD operand specifies the optional services that are to be used with the 
BDAM data set. These options are related to the type of addressing used, the 
extended search option, block position feedback, and write-validity checking. The 
following describes the characters that can be specified (the characters can be 
specified in any order and no commas are allowed between characters): 



A 



E 



Specifies that actual device addresses (MBBCCHHR) are provided to the system 
when READ or WRITE macro instructions are issued. 



F 



Specifies that the extended search option is used to locate data blocks or available 
space into which a data block can be added. When the extended search option is 
specified, the number of blocks or tracks to be searched must be specified in the 
LIMCT operand. The extended search option is ignored if actual addressing 
(OPTCD=A) is also specified. The extended search option requires that the data 
set have keys and that the search be made by key (by specifying DK in the READ 
or WRITE macro or DA in the WRITE macro). 

Specifies that block position feedback requested by a READ or WRITE macro 
instruction is to be in the same form that was originally presented to the system in 
the READ or WRITE macro instruction. If the F operand is omitted, the system 
provides feedback, when requested, in the form of an 8-byte actual device address. 
(Feedback is always provided if exclusive control is requested.) 

R 

Specifies that relative block addresses (in the form of a 3 -byte binary number) are 
provided to the system when a READ or WRITE macro instruction is issued. 

W 

Specifies that the system performs a validity check for each record written. 

Note: Relative track addressing can only be specified by omitting both A and R from 
the OPTCD operand. If you want to specify relative track addressing after your data 
set has been accessed using another addressing scheme (OPTCD = A or R), you should 
either specify a valid OPTCD operand (E, F, or W) in the DCB macro or DD card 
when you reopen your data set, or zero out the OPTCD = A or R bits in the data 
control block exit routine. Note that the first method will prevent the open routines 
from merging any of the other OPTCD bits from the format- 1 DSCB in the DCB. 
Both methods will update the OPTCD in the DSCB if the open is for OUTPUT, 
OUTIN, or UPDAT. 

Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the DCB open exit routine. 
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RECFM={U | V[S | BS] | F[T]} 

The RECFM operand specifies the format and characteristics of the records in the 
data set. The following describes the characters that can be coded (if the optional 
characters are coded, they must be coded in the order shown above): 

B 

Specifies that the data set contains blocked records. The record format 
RECFM=VBS is the only combination in which B can be specified. RECFM=VBS 
does not cause the system to process spanned records; the problem program must 
block and segment the records. RECFM =VBS is treated as a variable-length record 
by BDAM. 

F 

Specifies that the data set contains fixed-length records. 

S 

Specifies that the data set contains variable-length spanned records when it is 
coded as RECFM=VS. When RECFM=VBS is coded, the records are treated as 
variable-length records, and the problem program must block and segment the 
records. 

T 

Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be partially written on one track and the 
remainder is written on the following track (if required). 

U 

Specifies that the data set contains undefined-length records. 

V 

Specifies that the data set contains variable-length records. 

Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, the problem program before completion of the 
data control block exit routine, or by the data set label of an existing data set. 

SYNAD=relexp 

The SYNAD operand specifies the address of the error analysis routine to be given 
control when an uncorrectable input/output error occurs. The contents of the 
registers when the error analysis routine is given control are described in Appendix A 
of this publication. 

The error analysis routine must not use the save area pointed to by register 13 because 
this area is used by the system. The system does not restore registers when it regains 
control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered. When a 
BDAM data set is being created, a return from the error analysis routine to the system 
causes abnormal termination of the task. 

If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCB — Construct a Data Control Block (BISAM) 

The data control block for the basic indexed sequential access method (BISAM) is 
constructed during assembly of the problem program. The DCB macro instruction must 
not be coded within the first 16 bytes of addressability for the control section (CSECT). 
The DSORG and MACRF operands must be coded in the DCB macro instruction, but 
the other DCB operands can be supplied from other sources. Each BISAM DCB operand 
description contains a heading, "Source." The information under this heading describes 
the sources from which the operand can be supplied to the data control block. 

Before a DCB macro instruction for a BISAM data set is coded, the following 
characteristics of BISAM data sets should be considered: 

• BISAM cannot be used to create an indexed sequential data set. 

• BISAM performs the functions of direct retrieval of a logical record by key, direct 
update-in-place for a block of records, direct insertion of a new record in its correct 
key sequence. 

• Buffering can be controlled by the problem program, or dynamic buffering can be 
specified in the DCB macro instruction and subsequently requested in a READ macro 
instruction. 

• The problem program must synchronize I/O operations by issuing a CHECK or 
WAIT macro instruction to test for completion of Read and Write operations. 

• Additional DCB operands provide the capability of reducing input/output operations 
by defining work areas to contain the highest level master index and the records being 
processed. 

For additional information about the characteristics of BISAM processing, refer to 
OS/VS2 MVS Data Management Services Guide. 

The DCB macro for BISAM is written as follows: 



[symbol] 


DCB 


[BFALN={F|D}] 
[BUFCB= relexp] 
[BUFL= absexp ] 
[BUFNO= absexp] 
[DDNAME= symbol ]i 
DSORG=IS 
[EXLST= relexp] 

MACRF= {(R[S][C]) } 

{(W{U[A] | A}[C]) } 

f(R[U[S] I S][C],W{U[A] | A}[C])} 

[MSHI= relexp] 
[MSWA= relexp] 
[NCP= absexp] 
[SMSI= absexp] 
[SMSW= absexp] 
[SYNAD= relexp] 



'This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 



52 OS/VS2 Data Management Macro Instructions 



DCB— BISAM 

The following describes the DCB operands that can be supplied when the basic indexed 
sequential access method is used: 

BFALN={F|D} 

The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is acquired for use with dynamic buffering or when the 
buffer pool is constructed by a GETPOOL macro instruction. If the BFALN operand 
is omitted, the system provides doubleword alignment for each buffer. The following 
describes the characters that can be specified: 

F 

Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 

D 

Specifies that each buffer is on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool or the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BUFCB=relexp 

The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. 

If dynamic buffering is requested or the buffer pool is constructed by a GETPOOL 
macro instruction, the system places the address of the buffer pool control block into 
the data control block, and the BUFCB operand must be omitted. The BUFCB 
operand must be omitted if the problem program controls all buffering. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

BJJFL=absexp (maximum value is 32,760) 

The BUFL operand specifies the length of each buffer to be constructed by a BUILD 
or GETPOOL macro instruction. When the data set is opened, the system computes 
the minimum length required and verifies that the length in the buffer pool control 
block is equal to or greater than the minimum required. The system then inserts the 
computed length into the BUFL field of the data control block. 

If dynamic buffering is requested, the system computes the buffer length required, and 
the BUFL operand is not required. 

If the problem program controls all buffering, the BUFL operand is not required. 
However, an ISAM data set requires additional buffer space for system use. For a 
description of the buffer length required for various ISAM operations, refer to 
OS/VS2 MVS Data Management Services Guide. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 



Macro Instruction Descriptions 53 



BUFNO=absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers requested for use with dynamic 
buffering, or it specifies the number of buffers to be constructed by a BUILD macro 
instruction. If dynamic buffering is requested but the BUFNO operand is omitted, the 
system automatically acquires two buffers for use with dynamic buffering. 

If the GETPOOL macro instruction is used to construct the buffer pool, the BUFNO 
operand is not required. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

DDNAME=symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition statement that defines the ISAM data set to be processed. 

Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 

DSORG=IS 

The DSORG operand specifies the indexed sequential organization of the data set. IS 
is the only combination of characters that can be coded for BISAM. 

Source: The DSORG operand must be coded in the DCB macro instruction as well as 
in the DCB subparameter of a DD statement unless it is for a data set passed from a 
previous job step. In this case, DSORG may be omitted from the DD statement. 

EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program uses the data control block exit 
routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 

Refer to Appendix D of this publication for the format and requirements for exit list 
processing. For additional information about exit list processing, refer to OS/ VS2 
MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the associated exit is required. 

MACRF= {(R[S][C]) } 

{(W{U[A]|A}[C]) } 

{(R[U[S]|S][C],W{U[A]|A}[C])} 
The MACRF operand specifies the type of macro instructions (READ, WRITE, 
CHECK, WAIT, and FREEDBUF) and type of processing (add records, dynamic 
buffering, and update records) to be used with the data set being processed. The 
operand can be coded in any of the combinations shown above; the following 
describes the characters that can be coded: 

A 

Specifies that new records are to be added to the data set. This character must be 
coded if WRITE KN macro instructions are used with the data set. 

C 

Specifies that the CHECK macro instruction is used to test I/O operations for 
completion. If C is not coded, WAIT macro instructions must be used. 

R 

Specifies that READ macro instructions are used. 
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s 



u 



DCB— BISAM 

Specifies that dynamic buffering is requested in READ macro instructions. S should 
not be specified if the problem program provides the buffer pool. 

Specifies that records in the data set will be updated in place. If U is coded in 
combination with R, it must also be coded in combination with W. For example, 
MACRF=(RU,WU). 

W 

Specifies that WRITE macro instructions are used. 

Source: The MACRF operand must be coded in the DCB macro instruction. 

MSHl= relexp 

The MSHI operand specifies the address of the storage area used to contain the 
highest level master index for the data set. The system uses this area to reduce the 
search time required to find a given record in the data set. The MSHI operand is 
coded only when the SMSI operand is coded. 

Source: The MSHI operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

MSWA=relexp 

The MSWA operand specifies the address of the storage work area to be used by the 
system when new records are being added to the data set. This operand is optional, 
but the system acquires a minimum-size work area if the operand is omitted. The 
MSWA operand is coded only when the SMSW operand is coded. 

Processing efficiency can be increased if more than a minimum-size work area is 
provided. For more detailed information about work area size, refer to OS/VS2 
MVS Data Management Services Guide. 

Note: QISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields in the data 
control block as a work area; these fields contain meaningful information only when 
the data set is opened for BISAM. 

Source: The MSWA operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

NCP=absexp (maximum value is 99) 

The NCP operand specifies the maximum number of READ/WRITE macro 
instructions that are issued before the first CHECK (or WAIT) macro instruction is 
issued to test for completion of the I/O operation. The maximum number that can be 
specified may be less than 99 depending on the amount of virtual storage available in 
the region or partition. If the NCP operand is omitted, one is assumed. If dynamic 
buffering is used, the value specified for the NCP operand must not exceed the 
number of buffers specified in the BUFNO operand. 

Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. 
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SMSl=absexp (maximum value is 65,535) 

The SMSI operand specifies the length, in bytes, required to contain the highest level 
master index for the data set being processed. The size required can be determined 
from the DCBNCRHI field of the data control block. When an ISAM data set is 
created (with QISAM), the size of the highest level index is inserted into the 
DCBNCRHI field. If the value specified in the SMSI operand is less than the value in 
the DCBNCRHI field, the task is abnormally terminated. 

Note: QISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields as a work 
area; these fields contain meaningful information only when the data set is opened for 
BISAM. 

Source: The SMSI operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

SMSW=absexp (maximum value is 65,535) 

The SMSW operand specifies the length, in bytes, of a work area that is used by 
BISAM. This operand is optional, but the system acquires a minimum-size work area 
if the operand is omitted. The SMSW operand is coded only when the MSWA 
operand is also coded. If the SMSW operand is coded but the size specified is less 
than the minimum required, the task is abnormally terminated. OS/VS2 MVS Data 
Management Services Guide describes the methods of calculating the size of the 
work area. 

If unblocked records are used, the work area must be large enough to contain all the 
count fields (eight bytes each), key fields, and data fields contained on one 
direct-access device track. 

If blocked records are used, the work area must be large enough to contain all the 
count fields (eight bytes each) and data fields contained on one direct-access device 
track plus additional space for one logical record (LRECL value). 

Note: QISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields in the data 
control block as a work area; these fielH iin meaningful information only when 

the data set is opened for BISAM. 

Source: The SMSW operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

SYNAD=relexp 

The SYNAD operand specifies the address of the error anlaysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 

The error anlaysis routine must not use the save area pointed to by register 1 3 because 
this area is used by the system. The system does not restore registers when it regains 
control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered. If the error 
analysis routine continues processing, the results are unpredictable. 

If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error analysis routine 
address at any time. 
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The data control block for the basic partitioned access method (BPAM) is constructed 
during assembly of the problem program. The DCB macro instruction can be coded at 
any point in a control section (CSECT). The DSORG and MACRF operands must be 
specified in the DCB macro instruction, but the other DCB operands can be supplied 
from other sources. Each of the BPAM DCB operand descriptions contains a heading, 
"Source." The information under this heading describes the sources which can supply the 
operand to the data control block. 

Before a DCB macro instruction for a BPAM data set is coded, the following 
characteristics of partitioned data sets should be considered: 

• The entire partitioned data set must reside on one direct-access volume, but several 
such data sets, on the same or different volumes, can be concatenated for input. 

• When a partitioned data set is being created, the first (or only) DD statement for the 
data set must contain a SPACE parameter defining the size of the entire data set and 
its directory. From this information, the system allocates space for the data set-and 
pre-formats the data set directory. As subsequent data set members are added, they 
are added in the space originally allocated. 

• A single member of a partitioned data set can be added or retrieved using BSAM or 
QSAM without using the BLDL, FIND, or STOW macro instructions. In this case, the 
data set member is being processed as a sequential data set (DSORG=PS). Processing 
a member in this manner does not provide the full capability of the basic partitioned 
access method. For more information about processing a member using BSAM or 
QSAM, refer to OS/VS2 MVS Data Management Services Guide. 

• A single member or multiple members can be added, retrieved, or updated using 
BPAM (many of the routines used by BPAM are actually BSAM routines). 

• Buffers for a BPAM data set can be acquired automatically, but buffer control must 
be provided by the problem program. The problem program must issue a READ 
macro instruction that provides a buffer address to fill an input buffer, and it must 
place the data in an output buffer before issuing a WRITE macro instruction to write 
a data block. 

• Although a BPAM data set can contain blocked records, the problem program must 
perform all blocking and deblocking of records. BPAM provides only the capability to 
read or write a data block, but the data block can contain multiple logical records 
assembled by the problem program. 

• The STOW macro instruction can be used to add, delete, change, or replace a member 
name or alias in the directory. 

• Multiple members of the data set can be processed by building a list of member 
locations (with a BLDL macro instruction) and using the FIND macro instruction (in 
conjunction with the list) to locate the beginning of each member. 

• The problem program must synchronize I/O operations by issuing a CHECK macro 
instruction for each READ or WRITE macro instruction issued. 

These characteristics of partitioned data sets and the basic partitioned access method are 
described in more detail in OS/VS2 MVS Data Management Services Guide. 
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The DCB macro for BPAM is written as follows: 



[symbol] 


DCB 


[BFALN={F|D}] 
[BLKSIZE= absexp] 
[BUFCB= relexp] 
[BUFL= absexp ] 
[BUFNO= absexp ] 
[DDNAME= symbol]* 
DSORG={PO|POU} 
[EODAD= relexp] 
[EXLST= relexp ] 
[KEYLEN= absexp] 
[LRECL= absexp ] 
MACRF={(R|W|R,W)}i 
[NCP= absexp ] 
[OPTCD={C|W[C]}] 

[RECFM={U[T][A|M] } 
{V[B[T]|T][A|M]} 
{F[B[T]|T][A|M]}] 

[SYNAT>= relexp] 



'This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 

The following describes the DCB operands that can be specified when a BPAM data set 
is being created or processed: 

BFALN={F|D} 

The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides doubleword 
alignment for each buffer. The following describes the characters that can be specified 
in the BFALN operand: 

F 

Specifies that each buffer is aligned on a fullword boundary that is not also a 
doubleword boundary. 

D 

Specifies that each buffer is aligned on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction* in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BLKSlZE—absexp (maximum value is 32,760) 

The BLKSIZE operand specifies the length, in bytes, of each data block for 
fixed-length records, or it specifies the maximum length, in bytes, for variable-length 
or undefined-length records. If keys are used, the length of the key is not included in 
the value specified for the BLKSIZE operand. 

The actual block size that can be specified depends on the record format and the type 
of direct-access device being used. If the track-overflow feature is used, the block size 
can be up to the maximum. If the track-overflow feature is not used, the maximum 
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block size is determined by the track capacity of a single track on the direct-access 
device being used. Device capacity for direct-access devices is described in Appendix 
C of this publication. For additional information about device capacity and space 
allocation, refer to OS/VS2 MVS Data Management Services Guide. 

For variable-length records, the value specified in the BLKSIZE operand must include 
the maximum logical record length (up to 32,756 bytes) plus four bytes for the block 
descriptor word (BDW). 

For undefined-length records, the value specified for the BLKSIZE operand can be 
altered by the problem program when the actual length becomes known to the 
problem program. The value can be inserted into the DCBBLKSI field of the data 
control block or specified in the length operand of a READ/WRITE macro 
instruction. 

Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

BUFCB=relexp 

The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. 

If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block and the BUFCB operand can be omitted. Also, if the problem program controls 
all buffering, the BUFCB operand should be omitted. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

B\JFL=absexp (maximum value is 32,760) 

The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is acquired automatically. If the BUFL operand is omitted and 
the buffer pool is acquired automatically, the system acquires buffers with a length 
that is equal to the sum of the values specified in the KEYLEN and BLKSIZE 
operands. If the problem program requires longer buffers, the BUFL operand should 
be specified. 

If the problem program controls all buffering, the BUFL operand is not required. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BUFNO =absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers to be acquired automatically 
by the system. 

If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL macro instruction, the BUFNO operand should be omitted. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

DDNAME =symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 
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Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 

DSORG={PO|POU} 

The DSORG operand specifies the data set organization and if the data set contains 
any location-dependent information that would make it unmovable. The following 
describes the characters that can be specified: 

PO 

Specifies a partitioned data set organization. 

POU 

Specifies a partitioned data set organization and that the data set contains 
location-dependent information. 

Note: If BSAM or QSAM is used to add or retrieve a single member of a partitioned 
data set, a sequential access method is being used, and the DSORG operand is 
specified as PS or PSU. The name of the member being processed in this manner is 
supplied in a DD statement. 

Source: The DSORG operand must be specified in the DCB macro instruction. 

EODAD=r<?/ejtp 

The EODAD operand specifies the address of the routine given control when the end 
of the input data set is reached. Control is given to this routine when an input request 
is made (READ macro instruction) and there are no additional input records to 
retrieve. The routine is entered when a CHECK macro instruction is issued and the 
end of the data set is reached. If the end of the data set is reached and no EODAD 
address has been supplied, the task is abnormally terminated. For additional 
information on the EODAD routine, see OS/VS2 MVS Data Management Services 
Guide. 

Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 

EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program uses the data control block exit 
routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 

Refer to Appendix D of this publication for the format and requirements of the exit 
list processing. For additional information about exit list processing, refer to OS/VS2 
MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the' OPEN macro instruction is issued to open the data set. 

KE\LEN=absexp (maximum value is 255) 

The KEYLEN operand specifies the length, in bytes, of the key associated with each 
data block in the direct-access device data set. If the key length is not supplied from 
any source by the end of the data control block exit routine, a key length of zero (no 
keys) is assumed. 

Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by the data set label of an 
existing data set. If KEYLEN =0 is specified in the DCB macro instruction, a special 
indicator is set in RECFM so that KEYLEN cannot be supplied from the DCB 
subparameter of a DD statement or data set label of an existing data set. KEYLEN =0 
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can be coded only in the DCB macro instruction and will be ignored if specified in the 
DD statement. 

LRECL=absexp (maximum value is 32,760) 

The LRECL operand specifies the length, in bytes, of each fixed-length logical record 
in the data set; It is required only for fixed-length records. The value specified in the 
LRECL operand cannot exceed the value specified in the BLKSIZE operand. 

If the records are unblocked, the value specified in the LRECL operand must equal 
the value specified in the BLKSIZE operand. If the records are blocked, the value 
specified in the LRECL operand must be evenly divisible into the value specified in 
the BLKSIZE operand. 

Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

MACRF={(R|W|R,W)} 

The MACRF operand specifies the type of macro instructions (READ, WRITE, and 
NOTE/POINT) that are used to process the data set. The following describes the 
characters that can be specified: 

R 

Specifies that READ macro instructions are used. This operand automatically 
provides the capability to use both the NOTE and POINT macro instructions with 
the data set. 

W 

Specifies that WRITE macro instructions are used. This operand automatically 
provides the capability to use both the NOTE and POINT macro instructions with 
the data set. 

All BPAM READ and WRITE macro instructions issued must be tested for 
completion using a CHECK macro instruction. The MACRF operand does not require 
any coding to specify that a CHECK macro instruction will be used. 

Source: The MACRF operand must be specified in the DCB macro instruction. 

NCP=absexp (maximum value is 99) 

The NCP operand specifies the maximum number of READ and WRITE macro 
instructions that will be issued before the first CHECK macro instruction is issued. 
The maximum number may be less than 99 depending on the amount of virtual 
storage available in the region or partition. If chained scheduling is specified, the value 
of NCP determines the maximum number of channel program segments that can be 
chained and must be specified as more than one. If the NCP operand is omitted, one is 
assumed. 

Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. 
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OPTCD={C|W[C]} 

The OPTCD operand specifies the optional services performed by the system. The 
following describes the characters that can be specified; they can be specified in any 
order and no commas are allowed between characters: 

C 

Specifies that chained scheduling is used. 

Note: Chained scheduling is supported whether requested or not, except where it is 
not allowed. See OS/ VS2 MVS Data Management Services Guide for 
conditions where chained scheduling is not allowed. 

W 

Specifies that the system performs a validity check for each record written. 

Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. However, all optional services must be 
requested from the same source. 

RECFM= {U[T][A | M] } 

{V[B[T]|T][A|M]} 

{F[B[T]|T][A|M]} 
The RECFM operand specifies the record format and characteristics of the data set 
being created or processed. All the record formats shown above can be specified, but 
in those formats that show blocked records, the problem program must perform the 
blocking and deblocking of logical records; BPAM recognizes only data blocks. The 
following describes the characters that can be specified: 



A 

B 
F 

M 



Specifies that the records in the data set contain American National Standards 
Institute (ANSI) control characters. Refer to Appendix E for a description of 
control characters. 

Specifies that the data set contains blocked records. 

Specifies that the data set contains fixed-length records. 

Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. 

T 

Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track of a 
direct-access device and the remainder of the record written on the following track 
(if required). Chained scheduling (OPTCD =C) cannot be used if the 
track-overflow feature is used. 

U 

Specifies that the data set contains undefined-length records. 

V 

Specifies that the data set contains variable-length records. 

Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 



62 OS/VS2 Data Management Macro Instructions 



DCB— BPAM 

SYNAD=relexp 

The SYNAD operand specifies the address of the error analysis (SYNAD) routine to 
be given control when an uncorrectable input/output error occurs. The contents of 
the registers when the error analysis routine is given control are described in 
Appendix A. 

The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can return 
control to the system by issuing a RETURN macro instruction. If control is returned 
to the system, the system returns control to the problem program and proceeds as 
though no error had been encountered. 

If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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The data control block for the basic sequential access method (BSAM) is constructed 
during assembly of the problem program. The DSORG and MACRF operands must be 
coded in the DCB macro instruction, but the other DCB operands can be supplied, to the 
data control block, from other sources. Each DCB operand description contains a 
heading, "Source." The information under this heading describes the sources from which 
an operand can be supplied. 

Before a DCB macro instruction for creating or processing a BSAM data set is coded, the 
following characteristics of BSAM data sets should be considered: 

• Although several record formats with blocked records can be specified for BSAM, the 
problem program must perform all blocking and deblocking of records. BSAM 
provides only the capability to read or write a data block, but the block can contain 
one or more logical records assembled by the problem program. 

• Buffers for a BSAM data set can be acquired automatically, but buffer control must 
be provided by the problem program. The problem program must issue a READ 
macro instruction that provides a buffer address to fill an input buffer, and it must 
place the data in an output buffer before issuing the WRITE macro instruction to 
write a data block. 

• The problem program must synchronize I/O operations by issuing a CHECK macro 
instruction for each READ and WRITE macro instruction issued. 

• BSAM provides capability for nonsequential processing by using the NOTE and 
POINT macro instructions. 

• Keys for direct-access device records can be read or written using BSAM. 

• Specifying the DEVD operand in the DCB macro instruction can make the program 
device dependent. 

These characteristics of basic sequential access method data sets are described in more 
detail in OS/VS2 MVS Data Management Services Guide. 

For information on additional operands for the DCB macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275. 

For information on additional operands for the DCB macro for the 3886, see OS/VS 
IBM 3886 Optical Character Reader Model 1 Reference. 
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The DCB macro for BSAM is written as follows: 



[symbol] 



DCB 



[BFALN={F|D}] 
[BFTEK=R] 
[BLKSIZE=aZw<?Jcp] 
[BUFCB= relexp] 
[BUFL= absexp] 
[BUFNO= absexp] 
[BUFOFF= {absexp | L}] 
[DDNAME= symbol^ 

[DEVD= {DA 

[,KEYLEN= absexp] 

{TA 

[,DEN={0|1|2|3|4}] 
[,TRTCH={C|E|ET|T}] 

{PT 
[,CODE={A | B | C | F 1 1 1 N | T}] 

{PR 

[,PRTSP={0|1|2|3}] 



} 



{PC 

[,MODE=[C|E][R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | 

RW[T] | RWP[XT][D] | W[T]}] } 

{RD 
[,MODE=[C | E][0 | R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | 

RW[T] | RWP[XT][D] | W[T]}] }] 

DSORG={PS|PSU} 
[EODAD= relexp ] 
[EXLST= relexp] 
[KEYLEN= absexp] 
[LKECL={absexp | X}] 

MACRF= {(R[C | P]) } 

{(W[C|P|L]) } 

{(R[C|P],W[C|P])}i 
[NCP= absexp] 



^This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 

Continued on next page. 
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[OPTCD= {B } 
{T } 

|U[C] } 

{C[T][B][U] } 

{H[Z][B] } 

{J[C][U] } 

{W[C][T][B][U]} 

{Z[C][T][B][u]} 

{Q[C][B][T|Z]}] 
[RECFM= {U[T][A | M] } 

{V[B|S|T|BS|BT][A|M]} 

{D[B][A] } 

{F[B|S|T|BS|BT][A|M]}] 
[SYNAD=relexp] 



The following describes the operands that can be specified in the DCB macro instruction 
for a BSAM data set: 

BFALN={F|D} 

The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides doubleword 
alignment for each buffer. 

If the data set being created or processed contains ASCII tape records with a block 
prefix, the block prefix is entered at the beginning of the buffer, and data alignment 
depends on the length of the block prefix. For a description of how to specify the 
block prefix length, refer to the DCB BUFOFF operand. 

The following describes the characters that can be specified: 

F 

Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 

D 

Specifies that each buffer is on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied by the same source. 

BFTEK=R 

The BFTEK=R operand specifies that BSAM is used to read unblocked 
variable-length spanned records with keys from a BDAM data set. Each read 
operation reads one segment of the record and places it in the area designated in the 
READ macro instruction. The first segment enters at the beginning of the area, but 
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all subsequent segments are offset by the length of the key (only the first segment has 
a key). The problem program must provide an area in which to assemble a record, 
identify each segment, and assemble the segments into a complete record. 

Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 

BLKSlZE=absexp (maximum value is 32,760) 

The BLKSIZE operand specifies the maximum block length in bytes. For fixed-length, 
unblocked records, this operand specifies the record length. The BLKSIZE operand 
includes only the data block length; if keys are used, the length of the key is not 
included in the value specified for the BLKSIZE operand. 

The actual value that can be specified in the BLKSIZE operand depends on the device 
type and the record format being used. Device capacity is shown in Appendix C of 
this publication. For additional information about device capacity, refer to OS/VS2 
MVS Data Management Services Guide. For direct-access devices when the 
track-overflow feature is used or variable-length spanned records are being processed, 
the value specified in the BLKSIZE operand can be up to the maximum value. For 
other record formats used with direct-access devices, the value specified for BLKSIZE 
cannot exceed the capacity of a single track. 

If fixed-length records are used for a SYSOUT data set, the value specified in the 
BLKSIZE operand must be an integral multiple of the value specified for the logical 
record length (LRECL); otherwise the system will adjust the block size downward to 
the nearest multiple. 

If variable-length records are used, the value specified in the BLKSIZE operand must 
include the maximum logical record length (up to 32,756 bytes) plus the four bytes 
required for the block descriptor word (BDW). For format-D variable-length records 
(ASCII data sets), the minimum value for BLKSIZE is 18 bytes and the maximum 
value is 2,048 bytes. 

If ASCII tape records with a block prefix are processed, the value specified in the 
BLKSIZE operand must also include the length of the block prefix. 

If BSAM is used to read variable-length spanned records from a BDAM data set, the 
value specified for the BLKSIZE operand must be as large as the longest possible 
record segment in the BDAM data set, including four bytes for the segment descriptor 
word (SDW) and four bytes for the block descriptor word (BDW). 

If undefined-length records are used, the value specified for the BLKSIZE operand 
can be altered by the problem program when the actual length becomes known to the 
problem program. The value can be inserted directly into the DCBBLKSI field of the 
data control block or specified in the length operand of a READ/WRITE macro 
instruction. 

Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 
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BU¥CB=relexp 

The BUFCB operand specifies the address of the buffer pool control block in a buffer 
pool constructed by a BUILD macro instruction. 

If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block, and the BUFCB operand should be omitted. If the problem program controls all 
buffering, the BUFCB operand is not required. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

BVFL=absexp (maximum value is 32,760) 

The BUFL operand specifies the length, in bytes, for each buffer in the buffer pool 
when the buffer pool is acquired automatically. The system acquires buffers with a 
length, equal to the sum of the values specified in the KEYLEN and BLKSIZE 
operands if the BUFL operand is omitted; if the problem program requires larger 
buffers, the BUFL operand must be specified. If the BUFL operand is specified, it 
must be at least as large as the value specified in the BLKSIZE operand. If the data set 
is for card image mode, the BUFL operand should be specified as 160. The description 
of the DEVD operand contains a description of card image mode. 

If the data set contains ASCII tape records with a block prefix, the value specified in 
the BUFL operand must include the block length plus the length of the block prefix. 

If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL or BUILD macro instruction, the BUFL operand is not required. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

B\JFNO=absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers constructed by a BUILD macro 
instruction or the number of buffers to be acquired automatically by the system. 

If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL macro instruction, the BUFNO operand should be omitted. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BUFOFF={ absexp | L} 

The BUFOFF operand specifies the length, in bytes, of the block prefix used with an 
ASCII tape data set. When BSAM is used to read an ASCII tape data set, the problem 
program must use the block prefix length to determine the location of the data in the 
buffer. When BSAM is used to write an output ASCII tape data set, the problem 
program must insert the block prefix into the buffer followed by the data (BSAM 
considers the block prefix as data). The block prefix and data can consist of any 
characters that can be translated into ASCII code; any character that cannot be 
translated is replaced with a substitute character. For format-D records, the RDW 
must be binary; if RECFM=D and BUFOFF=L, then the RDW and BDW must be 
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binary. On output, the control program translates the BDW and RDW to zoned 
decimal and on input, the control program converts them to binary. The following can 
be specified in the BUFOFF operand: 

absexp 

Specifies the length, in bytes, of the block prefix. This value can be from to 99 
for an input data set. The value must be for writing an output data set with 
fixed-length or undefined-length records (BSAM considers the block prefix part of 
the data record). 

L 

Specifies that the block prefix is 4 bytes long and contains the block length. 
BUFOFF=L is used when format-D records (ASCII) are processed. When 
BUFOFF=L is specified, the BSAM problem program can process the data records 
(using READ and WRITE macro instructions) in the same manner as if the data 
were in format-V variable-length records. For further information on this operand, 
see "Variable-Length Records — Format D" in OS/ VS2 MVS Data Management 
Services Guide. 

If the BUFOFF operand is omitted for an input data set with format-D records, the 
system inserts the record length into the DCBLRECL field of the data control block; 
the problem program must obtain the length from this field to process the record. 

If the BUFOFF operand is omitted from an output data set with format-D records, the 
problem program must insert the actual record length into the DCBBLKSI field of the 
data control block or specify the record length in the length operand of a WRITE 
macro instruction. 

Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. BUFOFF =absexp can also be 
supplied by the label of an existing data set; BUFOFF=L cannot be supplied by the 
label of an existing data set. 

DDNAME=symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 

Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 

DEVD={DA | TA | PT | PR | PC | RD}[, options] 

The DEVD operand specifies the device type on which the data set can or does reside. 
The device types above are shown with the optional operand(s) that can be coded 
when a particular device is used. The devices are listed in order of 
device-independence. For example, if DEVD=DA is coded in a DCB macro 
instruction (or the DEVD operand is omitted, which causes a default to DA), the data 
control block constructed during assembly could later be used for any of the other 
devices, but if DEVD=RD is coded, the data control block can be used only with a 
card reader or card reader punch. Unless you are certain that device interchangeability 
is not required, you should either code DEVD = DA or omit the operand and allow it to 
default to DA. 

If system input is directed to an intermediate storage device, the DEVD operand is 
omitted, and the job control language for the problem program designates the system 
input device to be used. Likewise, if system output is directed to an intermediate 
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storage device, the DEVD operand is omitted, and the job control language for the 
problem program designates the system output device to be used. 

If DEVD=PT is coded, the DCB macro should not be coded within the first 8 bytes 
of addressability for the control section (CSECT). If DEVD=PR, PC, or RD is 
coded, the DCB macro should not be coded within the first 1 6 bytes of addressability 
for the control section. 

The DEVD operand is discussed below according to individual device type: 

DEVD=DA 

[,KEYLEN= absexp] 

Specifies that the data control block can be used for a direct-access device (or any 

of the other device types described following DA). 

KEYLEN=absexp 

The KEYLEN operand can be specified only for data sets that reside on 
direct-access devices. Since the KEYLEN is usually coded without a DEVD 
operand (default taken), the description of the KEYLEN operand is in 
alphabetic sequence with the other operands. 

DEVD=TA 

[,DEN={0|1|2|3|4}] 

[,TRTCH={C|E|ET|T}] 

Specifies that the data control block can be used for a magnetic tape data set (or 

any of the other device types described following TA). If TA is coded, the following 

optional operands can be coded: 

DEN={0|1|2|3|4} 

The DEN operand specifies the recording density in the number of bits-per-inch 
per track as shown in the following chart: 



Recording Density 




DEN 7-Track Tape 


9-Track Tape 


200 


— 


1 556 


— 


2 800 


800 (NRZI)i 


3 — 


1600 (PE)2 


4 — 


6250 (GCR)3 



1 NRZI is for non-return-to-zero inverted mode 

2 PE is for phase encoded mode 

■* GCR is for group coded recording mode 

Note: Specifying DEN=0 for a 7-track 3420 tape attached to a 3803-1 will 
result in 556 bits-per-inch recording, but corresponding messages and tape labels 
will indicate 200 bits-per-inch recording density. 

If the DEN operand is not supplied by any source, the highest applicable density 
is assumed. 

TRTCH={C|E|ET|T} 

The TRTCH operand specifies the recording technique for 7-track tape. One of 
the above four character combinations can be coded. If the TRTCH operand is 
omitted, odd parity with no translation or conversion is assumed. The following 
describes the characters that can be specified: 



C 



E 



Specifies that the data-conversion feature is used with odd parity and no 
translation. 



Specifies even parity with no translation or conversion. 
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ET 

Specifies even parity with BCDIC to EBCDIC translation required and no 
data-conversion feature. 

T 

Specifies that BCDIC to EBCDIC translation is required with odd parity and 
no data-conversion feature. 

DEVD=PT 

[,CODE={A|B|C|F|I|N|T}] 

Specifies that the data control block is used for a paper tape device (or any of the 

other devices following PT). If PT is coded, the following optional operand can be 

coded: 

CODE={A|B|C|F|I|N|T} 

The CODE operand specifies the code in which the data was punched. The 
system converts these codes to EBCDIC code. If the CODE operand is not 
supplied by any source, CODE=I is assumed. The following describes the 
characters that can be specified: 

A 

Specifies 8-track tape in ASCII code. 

B 

Specifies Burroughs 7-track tape. 

C 

Specifies National Cash Register 8-track tape. 

F 

Specifies Friden 8-track tape. 

I 

Specifies IBM BCD perforated tape and transmission code with 8 tracks. 

N 

Specifies that no conversion is required. 

T 

Specifies Teletype' 5-track tape. 

DEVD=PR 

[,PRTSP={0|1|2|3}] 

Specifies that the data control block is used for an on-line printer (or any of the 
other device types following PR). If PR is coded, the following optional operand 
can be coded: 

PRTSP={0 | 1 | 2 | 3} 

The PRTSP operand specifies the line spacing on the printer. This operand is not 
valid if the RECFM operand specifies either machine (RECFM=M) or ANSI 
(RECFM=A) control characters. If the PRTSP operand is not specified from 
any source, one is assumed. The following describes the characters that can be 
specified: 



Specifies that spacing is suppressed (no space). 

1 

Specifies single-spacing. 



'Trademark of Teletype Corporation. 
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Specifies double-spacing (one blank line between printed lines). 

3 

Specifies triple-spacing (two blank lines between printed lines). 

DEVD=PC 

[,MODE=[C | E][R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]}] 

Specifies that the data control block is used for a card punch (or any of the other 

device types following PC). If PC is coded, the following optional operands can be 

specified: 

MODE=[C|E][R] 

The MODE operand specifies the mode of operation for the card punch. The 
following describes the characters that can be specified (if the MODE operand is 
omitted, E is assumed): 



C 



Specifies that the cards are to be punched in card image mode. In card image 
mode, the 12 rows in each card column are punched from two consecutive 
bytes in virtual storage. Rows 12 through 3 are punched from the low-order 6 
bits of one byte and rows 4 through 9 are punched from the low-order 6 bits 
of the following byte. 

Specifies that cards are to be punched in EBCDIC code. 

Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 



Note: If the MODE operand is specified in the DCB subparameter of a DD 
statement, either C or E must be specified if R is specified. 

STACK={1|2} 

The STACK operand specifies the stacker bin into which the card is placed after 
punching is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 

1 

Specifies stacker number 1 . 

2 

Specifies stacker number 2. 

FUNC={I | P | PW[XT}| R | RP[D] | RW[T] | RWP[XT][D] | W[T]} 

The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 

D 

Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output/punch portion of a read and punch or 
read punch and print operation. 
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I 

P 

R 
T 



Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 

Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 

Specifies that the data set is for reading cards. 

Specifies that the two-line print option is used. The two-line print option 
allows two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as. the 
data punched in the card, or it may be entirely different data. 

W 

Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 

X 

Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 

Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB parameter of the DD statement for the data set. 

DEVD=RD 

[,MODE=[C | E][0 | R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]}] 

Specifies that the data control block is used with a card reader or card read punch. 

If RD is specified, the data control block cannot be used with any other device 

type. When RD is coded, the following optional operands can be specified: 

MODE=[C|E][0|R] 

The MODE operand specifies the mode of operation for the card reader. The 
following describes the characters that can be specified: 

C 

Specifies that the cards to be read are in card image mode. In card image 
mode, the 12 rows in each card column are read into two consecutive bytes of 
virtual storage. Rows 12 through 3 are read into one byte and rows 4 through 
9 are read into the following byte. 



E 
O 



Specifies that the cards to be read contain data in EBCDIC code. 

Specifies that the program runs in optical-mark-read mode (3505 card 
reader). 



R 

Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 
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Note: If the MODE operand for a 3505 or 3525 is specified in the DCB 
subparameter of a DD statement, either C or E must be specified if R or O is 
specified. 

STACK={1|2} 

The STACK operand specifies the stacker bin into which the card is placed after 
reading is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 

1 

Specifies stacker number 1. 

2 

Specifies stacker number 2. 

FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]} 

The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 



D 



I 

P 

R 
T 



Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output/punch portion of a read and punch or 
read punch and print operation. 

Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 

Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 



Specifies that the data set is for reading cards. 

Specifies that the two-line print option is used. The two-line print option 
allows two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 

W 

Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 

X 

Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 

Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 
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Source: The DEVD operand can be supplied only in the DCB macro instruction. 
However, the optional operands can be supplied in the DCB macro instruction, the 
DCB subparameter of a DD statement, or by the problem program before 
completion of the data control block exit routine. 

DSORG={PS|PSU} 

The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following can be specified: 

PS 

Specifies a physical sequential data set. 

PSU 

Specifies a physical sequential data set that contains location-dependent 
information that would make it unmovable. 

Source: The DSORG operand must be coded in the DCB macro instruction. 

EODAD=relexp 

The EODAD operand specifies the address of the routine given control when the end 
of an input data set is reached. If the record format is RECFM=FS or FBS, the 
end-of-data condition is sensed when a file mark is read or when more data is 
requested after reading a truncated block. The end of data routine is entered when the 
CHECK macro instruction determines that the READ macro instruction reached the 
end of the data. If the end of the data set is reached but no EODAD address has been 
supplied, the task is abnormally terminated. See OS/VS2 MVS Data Management 
Services Guide for additional information on the EODAD routine. 

When the data set has been opened for UPDAT and volumes are to be switched, the 
problem program should issue a FEOV macro instruction after the EODAD routine 
has been entered. 

Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 

EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program requires additional processing for 
user labels, user totaling, data control block exit routine, end-of-volume, block count 
exits, to define a forms control buffer (FCB) image, use the JFCBE exit (for the 3800 
printer), or to use the DCB ABEND exit for ABEND condition analysis. 

Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit list processing, refer to OS/VS2 
MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program any time before the exit is required by the problem program. 

KEYLEN=absexp (maximum value is 255) 

The KEYLEN operand specifies the length, in bytes, for the key associated with each 
data block in a direct-access device data set. If the key length is not supplied from any 
source before completion of the data control block exit routine, a key length of zero 
(no keys) is assumed. 
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Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by the data set label of an 
existing data set. If KEYLEN=0 is specified in the DCB macro instruction, a special 
indicator is set in RECFM so that KEYLEN cannot be supplied from the DCB 
subparameter of a DD statement or data set label of an existing data set. KEYLEN =0 
can be coded only in the DCB macro instruction and will be ignored if specified in the 
DD statement. 

LRECL= {absexp\X} 

The LRECL operand specifies the length, in bytes, for fixed-length records, or it 
specifies the maximum length, in bytes, for variable-length records. LRECL=X is used 
for variable-length spanned records that exceed 32,756 bytes. Except when 
variable-length spanned records are used, the value specified for the LRECL operand 
cannot exceed the value specified for the BLKSIZE operand. 

Except when variable-length spanned records are used, the LRECL operand can be 
omitted for BSAM; the system uses the value specified in the BLKSIZE operand. If 
the LRECL value is coded, it is coded as described in the following. 

For fixed-length records that are unblocked, the value specified in the LRECL 
operand should be equal to the value specified in the BLKSIZE operand. For blocked 
fixed-length records, the value specified in the LRECL operand should be evenly 
divisible into the value specified in the BLKSIZE operand. 

For variable-length records, the value specified in LRECL must include the maximum 
data length (up to 32,752 bytes) plus 4 bytes for the RD W. 

For undefined-length records, the LRECL operand should be omitted; the actual 
length can be supplied dynamically in a READ/WRITE macro instruction. When an 
undefined-length record is read, the actual length of the record is returned by the 
system in the DCBLRECL field of the data control block. 

When BSAM is used to create a BDAM data set with variable-length spanned records, 
the LRECL value should be the maximum data length (up to 32,752) plus four bytes 
for the record descriptor word (RDW), or if the logical record length is greater than 
32,756 bytes, LRECL=X is specified. 

Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

MACRF= {(R[C | P]) } 

KW[C|P|L]) } 

f(R[C|P],W[C|P])} 
The MACRF operand specifies the type of macro instructions (READ, WRITE, 
CNTRL, and NOTE/POINT) that are used with the data set being created or 
processed. The BSAM MACRF operand also provides the special form 
(MACRF=WL) for creating a BDAM data set. The MACRF operand can be coded in 
any of the forms shown above. The following characters can be coded: 

C 

Specifies that the CNTRL macro instruction is used with the data set. If C is 
specified to be used with a card reader, a CNTRL macro instruction must follow 
every input request. 

L 

Specifies that BSAM is used to create a BDAM data set. This character can be 
specified only in the combination MACRF=WL. 
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P 

Specifies that POINT macro instructions are used with the data set being created or 
processed. Specifying P in the MACRF operand also automatically provides the 
capability of using NOTE macro instructions with the data set. P should not be 
coded for SYSIN or SYSOUT data sets. (See explanations of NOTE and POINT 
macro instructions.) 

R 

Specifies that READ macro instructions are used. 

W 

Specifies that WRITE macro instructions are used. 

Note: Each READ and WRITE macro instruction issued in the problem program must 
be checked for completion by a CHECK macro instruction. 

Source: The MACRF operand must be specified in the DCB macro instruction. 

NCP=absexp (maximum value is 99) 

The NCP operand specifies the maximum number of READ/WRITE macro 
instructions that will be issued before the first CHECK macro instruction is issued to 
test for completion of the I/O operation. The maximum number may be less than 99 
depending on the amount of virtual storage available in the region or partition. If 
chained scheduling is specified (OPTCD=C), the value of NCP determines the 
maximum number of channel program segments that can be chained and must be 
specified as more than one. If the NCP operand is omitted, one is assumed. 

Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. 

OPTCD= {B } 

{T } 

{U[C] } 

{C[T][B][U] } 

MZ][B] } 

{J[C][U] } 
{W[C][T][B][U]} 

{Z[C][T][B][U] 1 
(Q[C][B][T|Z]} 

The OPTCD operand specifies the optional services that are used with the BSAM data 
set. Two of the optional services, OPTCD=B and OPTCD=H, cannot be specified in 
the DCB macro instruction. They are requested in the DCB subparameter of a DD 
statement. Since all optional services requests must be supplied by the same source, 
the OPTCD operand must be omitted from the DCB macro instruction if either of 
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these options is requested in a DD statement. The following describes the characters 
that can be specified — these characters can be specified in any order (in one of the 
combinations shown above), and no commas are allowed between characters: 

C 

Requests that chained scheduling be used. OPTCD=C cannot be specified if 
BFTEK=R is specified for the same data control block. Also, chained scheduling 
cannot be specified for associated data sets or printing on a 3525. For 5740- AM3 
chained scheduling is ignored for direct access devices. 

Note: Chained scheduling is used whether requested or not, except where it is not 
allowed. See OS/VS2 MVS Data Management Services Guide for conditions 
where chained scheduling is not allowed. 

J 

Specifies that the first data byte in the output data line will be a 3800 table 
reference character. This table reference character selects a particular character 
arrangement table for the printing of the data line and can be used singularly or in 
conjunction with ANSI or machine control characters. This option is valid only for 
the 3800 Printing Subsystem. For information on the table reference character and 
character arrangement table modules, see IBM 3800 Printing Subsystem 
Programmer's Guide. 

Q 

Requests that ASCII tape records in an input data set be converted to EBCDIC 
code after the input record has been read. Translation is done at CHECK time for 
input. It also requests that an output record in EBCDIC code be converted to 
ASCII code before the record is written. For further information on this 
conversion, see "Variable-Length Records — Format D" in OS/VS2 MVS Data 
Management Services Guide. To determine the ASCII to EBCDIC or EBCDIC to 
ASCII translation codes, see System/ 3 70 Reference Summary, GX20-1850. 

Requests the user totaling f acility. If this facility is requested, the EXLST operand 
should specify the address of an exit list to be used. T cannot be specified for 
SYSIN and SYSOUT data sets. 

Specified only for a printer with the universal character set (UCS) feature or the 
3800 Printing Subsystem. This option unblocks data checks (permits them to be 
recognized as errors) and allows analysis by the appropriate error analysis routine 
(SYNAD routine). If the U option is omitted, data checks are not recognized as 
errors. 

For the IBM Mass Storage System(MSS): U requests window processing to reduce 
the amount of staging space required to process large sequential data sets on MSS. 
DSORG must specify physical sequential, allocation must be in cylinders, and type 
of I/O accessing must be either INPUT only or OUTPUT only. 

W 

Specifies that the system performs a validity check on each record written on a 
direct-access device. 



T 



U 
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Z 

For magnetic tape, input only, the Z option requests the system to shorten its 
normal error recovery procedure to consider a data check as a permanent I/O error 
after five unsuccessful attempts to read a record. This option is available only if it is 
selected when the operating system is generated. OPTCD=Z is meant to be used 
when a tape is known to contain errors and there is no need to process every 
record. The error analysis routine (SYNAD) should keep a count of permanent 
errors and terminate processing if the number becomes excessive. 

For direct-access devices only, the Z option requests the system to use the search 
direct option to accelerate the input operations for a data set. OPTCD=Z cannot 
be specified with spanned, standard, or track-overflow records. 

5740-AM3 only: For direct-access devices only, the Z option is ignored. 
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Note: The following describes the optional services that can be requested in the DCB 
subparameter of a DD statement. If either of these options is requested, the complete 
OPTCD operand must be supplied in the DD statement. 



B 



If OPTCD=B is specified in the DCB subparameter of a DD statement, it forces 
the end-of-volume (EOV) routine to disregard the end-of-file recognition for 
magnetic tape. When this occurs, the EOV routine uses the number of volume 
serial numbers to determine end of file. 



H 

If OPTCD=H is specified in the DCB subparameter of a DD statement, it specifies 
that the DOS/OS interchange feature is being used with the data set. 

Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, in the data set label for direct-access devices, 
I or by the problem program before completion of the DCB open exit routine or 
I JFCBE exit routine. However, all optional services must be requested from the same 
source. 

RECFM= {U[T][A | M] } 

{V[B|S|T|BS|BT][A|M]} 

{D[B][A] } 

{F[B | S | T | BS | BT][A | M] } 
The RECFM operand specifies the record format and characteristics of the data set 
being created or processed. All the record formats shown above can be specified, but 
in those record formats that specify blocked records, the problem program must 
perform the blocking and deblocking of logical records; BSAM recognizes only data 
blocks. The following describes the characters that can be specified: 



A 

B 
D 

F 
M 



Specifies that the records in the data set contain American National Standards 
Institute (ANSI) control characters. Refer to Appendix E for a description of 
control characters. 

Specifies that the data set contains blocked records. 

Specifies that the data set contains variable-length ASCII tape records. See 
OPTCD=Q and the BUFOFF operand for a description of how to specify ASCII 
data sets. 



Specifies that the data set contains fixed-length records. 

Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. RECFM=M cannot be 
used with ASCII data sets. 

For fixed-length records, S specifies that the records are written as standard blocks; 
the data set does not contain any truncated blocks or unfilled tracks, with the 
exception of the last block or track in the data set. Do not code S to retrieve 
records from a data set that was created using a RECFM other than standard. 
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For variable-length records, S specifies that a record can span more than one block. 
Spanned records can be read (reading a BDAM data set) or written (creating a 
BDAM data set) using BSAM. 

T 

Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track of a 
direct-access device and the remainder of the record written on the following track 
(if required). Chained scheduling cannot be used if the track-overflow feature is 
used. 

U 

Specifies that the data set contains undefined-length records. 

V 

Specifies that the data set contains variable-length records. 

Notes: 

• RECFM=V cannot be specified for a card reader data set or an ASCII tape data 
set. 

• RECFM=VBS does not provide the spanned record function; if this format is used, 
the problem program must block and segment the records. 

• RECFM=VS or VBS cannot be specified for a SYSIN data set. 

• RECFM=V cannot be used for a 7-track tape unless the data conversion feature 
(TRTCH=C) is used. 

Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

SYNAD=relexp 

The SYNAD operand specifies the address of the error analysis (SYNAD) routine to 
be given control when an uncorrectable input/output error occurs. The contents of 
the registers when the error analysis routine is given control are described in Appendix 
A of this publication. 

The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. If control is returned to the system, the system returns control to the 
problem program and proceeds as though no error had been encountered. 

If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCB — Construct a Data Control Block (QISAM) 

The data control block for a queued indexed sequential access method (QISAM) data set 
is constructed during assembly of the problem program. The DCB macro instruction 
must not be coded within the first 16 bytes of addressability for the control section 
(CSECT). The DSORG and MACRF operands must be coded in the DCB macro 
instruction, but the other DCB operands can be supplied from other sources. Each 
QISAM DCB operand description contains a heading, "Source." The information under 
this heading describes the sources which can supply the operand to the data control 
block. 

Before a DCB macro instruction for a QISAM data set is coded, the following 
characteristics of QISAM should be considered: 

• The characteristics of a QISAM data set are established when the data set is created; 
these characteristics cannot be changed without reorganizing the data set. The 
following DCB operands establish the characteristics of the data set and can be coded 
only when creating the data set: BLKSIZE, CYLOFL, KEYLEN, LRECL, NTM, 
OPTCD, RECFM, and RKP. 

• The data set can contain the following record formats: Unblocked fixed-length 
records (F), blocked fixed-length records (FB), unblocked variable-length records 
(V), or blocked variable-length records (VB). 

• QISAM can create an indexed sequential data set (QISAM, load mode), add 
additional data records at the end of the existing data set (QISAM, resume load 
mode), update a record in place, or retrieve records sequentially (QISAM, scan 
mode). 

• The track-overflow feature cannot be used to create an ISAM data set. 

• When an indexed sequential data set is being created, space for the prime area of the 
data set, the overflow area of the data set, and the cylinder/master index(es) for the 
data set can be allocated on the same or separate volumes. For information about 
space allocation, refer to OS/ VS2 JCL. 

• The system automatically creates one track index for each cylinder in the data set and 
one cylinder index for the entire data set. The DCB NTM and OPTCD operands can 
be specified to indicate that the data set requires a master index(es); the system 
creates and maintains up to three levels of master indexes. OS/VS2 MVS Data 
Management Services Guide contains additional information about indexes for 
indexed sequential data sets. 

• A record deletion option can be specified (OPTCD=L) when the ISAM data set is 
created. This option allows a record to be flagged for deletion by placing a 
hexadecimal value of 'FF' in the first data byte of the record (first byte of a 
fixed-length record or fifth byte of a variable-length record). Records marked for 
deletion are ignored during sequential retrieval by QISAM. 

• Reorganization statistics can be obtained by specifying OPTCD=R when the ISAM 
data set is created. These statistics can be used by the problem program to determine 
the status of the overflow areas allocated to the data set. Reorganization of ISAM 
data sets is described in OS/VS2 MVS Data Management Services Guide. 

• When an ISAM data set is created, the records must be written with the keys in 
ascending order. 

These characteristics of queued indexed sequential access method data sets are described 
in more detail in OS/VS2 MVS Data Management Services Guide. 
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The DCB macro for QISAM is written as follows: 



[symbol] 


DCB 


[BFALN={F|DJ] 
[BLKSIZE= absexp ] 
[BUFCB= relexp] 
[BUFL= absexp ] 
[BUFNO= absexp] 
[CYLOFL= absexp] 
[DDNAME= symbol V 
DSORG= {IS | ISU} 
[EODAD= relexp] 
[EXLST= relexp] 
[KEYLEN= absexp] 
[LRECL= absexp ] 

MACRF= {(PM) } 

{(PL) } 

{(GM[,S{K|I}]) } 

{(GL[,S{K|I}][,PU])} 

[NTM= absexp ] 

[OPTCD=[I][L][M][R][U][W][Y]] 
[RECFM={V[B]|F[B]}] 
[RKP= absexp ] 
[SYNAD= relexp] 



'This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 

The following describes the DCB operands that can be specified when a QISAM data set 
is being created or processed: 

BFALN={F|pj 

The BFALN operand specifies the alignment of each buffer in the buffer pool when 
the buffer pool is constructed automatically or by a GETPOOL macro instruction. If 
the BFALN operand is omitted, the system provides doubleword alignment for each 
buffer. The following describes the characters that can be specified: 

F 

Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 

D 

Specifies that each buffer is on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool, the problem 
program must provide a storage area for the buffers and control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BLKSIZE=absexp (maximum value is device-dependent) 

The BLKSIZE operand specifies the length, in bytes, for each data block when 
fixed-length records are used, or it specifies the maximum length in bytes, for each 
data block when variable-length records are used. The BLKSIZE operand must be 
specified when an ISAM data set is created. When an existing ISAM data set is 
processed, the BLKSIZE operand must be omitted (it is supplied by the data set 
label). 
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Track capacity of the direct-access device being used must be considered when the 
BLKSIZE for an ISAM data set is specified. For fixed-length records, the sum of the 
key length, data length, and device overhead plus 10 bytes (for ISAM use) must not 
exceed the capacity of a single track on the direct-access device being used. For 
variable-length records the sum of the key length, block-descriptor word length, 
record-descriptor word length, data length, and device overhead plus 10 bytes (for 
ISAM use) must not exceed the capacity of a single track on the direct-access device 
being used. Device capacity and device overhead are described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/VS2 MVS Data Management Services Guide. 

If fixed-length records are used, the value specified in the BLKSIZE operand must be 
an integral multiple of the value specified in the LRECL operand. 

Source: When an ISAM data set is created, the BLKSIZE operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the BLKSIZE operand must be omitted from the 
other sources, allowing the data set label to supply the value. 

BVFCB= re lexp 

The BUFCB operand specifies the address of the buffer pool control block 
constructed by a BUILD macro instruction. 

If the system constructs the buffer pool automatically or if the buffer pool is 
constructed by a GETPOOL macro instruction, the system places the address of the 
buffer pool control block into the data control block, and the BUFCB operand should 
be omitted. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

BUFL=absexp (maximum value is 32,760) 

The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is constructed by a BUILD or GETPOOL macro instruction. 
When the data set is opened, the system computes the minimum buffer length required 
and verifies that the length in the buffer pool control block is equal to or greater than 
the minimum length required. The system then inserts the computed length into the 
data control block. 

The BUFL operand is not required for QISAM if the system acquires buffers 
automatically; the system computes the minimum buffer length required and inserts 
the value into the data control block. 

If the buffer pool is constructed with a BUILD or GETPOOL macro instruction, 
additional space is required in each buffer for system use. For a description of the 
buffer length required for various ISAM operations, refer to OS/VS2 MVS Data 
Management Services Guide. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

BUFNO=absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers to be acquired automatically 
by the system. If the BUFNO operand is omitted, the system automatically acquires 
two buffers. 
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If the GETPOOL macro instruction is used to construct the buffer pool, the BUFNO 
operand is not required. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

C\LOFL=absexp (maximum value is 99) 

The CYLOFL operand specifies the number of tracks on each cylinder that is reserved 
as an overflow area. The overflow area is used to contain records that are forced off 
prime area tracks when additional records are added to the prime area track in 
ascending key sequence. ISAM maintains pointers to records in the overflow area so 
that the entire data set is logically in ascending key sequence. Tracks in the cylinder 
overflow area are used by the system only if OPTCD=Y is specified. For a more 
complete description of cylinder overflow area, refer to the space allocation section of 
OS/VS2 MVS Data Management Services Guide. 

Source: When an ISAM data set is created, the CYLOFL operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the CYLOFL operand should be omitted, 
allowing the data set label to supply the operand. 

DDNAME=symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 

Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the 
data set. 

DSORG={IS|ISU} 

The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following characters can be specified: 

IS 

Specifies an indexed sequential data set organization. 

ISU 

Specifies an indexed sequential data set that contains location-dependent 
information. ISU can be specified only when an ISAM data set is created. 

Source: The DSORG operand must be specified in the DCB macro instruction. When 
an ISAM data set is created, DSORG=IS or ISU must also be specified in the DCB 
subparameter of the corresponding DD statement. 

EODAD=relexp 

The EODAD operand specifies the address of the routine to be given control when the 
end of an input data set is reached. For ISAM, this operand would apply only to scan 
mode when a data set is open for an input operation. Control is given to this routine 
when a GET macro instruction is issued and there are no more input records to 
retrieve. For additional information on the EODAD routine, see OS/VS2 MVS 
Data Management Services Guide. 

Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 
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EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required only if the problem program uses the data control block 
exit routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 

Refer to Appendix D of this publication for the format and requirements for exit list 
processing. For additional information about exit list processing, refer to OS/VS2 
MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the associated exit is required. 

KEYLEN=absexp (maximum value is 255) 

The KEYLEN operand specifies the length, in bytes, of the key associated with each 
record in an indexed sequential data set. When blocked records are used, the key of 
the last record in the block (highest key) is used to identify the block. However, each 
logical record within the block has its own identifying key which ISAM uses to access 
a given logical record. 

Source: When an ISAM data set is created the KEYLEN operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the KEYLEN operand must be omitted, allowing 
the data set level to supply the key length value. KEYLEN=0 is not valid for an ISAM 
data set. 

LRECh=absexp (maximum value is device-dependent) 

The LRECL operand specifies the length, in bytes, for fixed-length records, or it 
specifies the maximum length, in bytes, for variable-length records. The value 
specified in the LRECL operand cannot exceed the value specified in the BLKSIZE 
operand. When fixed, unblocked records are used and the relative key position (as 
specified in the RKP operand) is zero, the value specified in the LRECL operand 
should include only the data length (the key is not written as part of the fixed, 
unblocked record when RKP=0). 

The track capacity of the direct-access device being used must be considered if 
maximum length logical records are being used. For fixed-length records, the sum of 
the key length, data length, and device overhead plus 10 bytes (for ISAM use) must 
not exceed the capacity of a single track on the direct-access device being used. For 
variable-length records, the sum of the key length, data length, device overhead, 
block-descriptor- word length, and record-descriptor- word length plus 10 bytes (for 
ISAM use) must not exceed the capacity of a single track on the direct-access device 
being used. Device capacity and device overhead are described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/ VS2 MVS Data Management Services Guide. 

Source: When an ISAM data set is created, the LRECL operand can be supplied in the 
DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the LRECL operand must be omitted, allowing 
the data set label to supply the value. 
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MACRF= {(PM) } 

{(PL) } 

{(GM[,S{K|I}]) } 

{(GL[,S{K|I}][,PU])} 

The MACRF operand specifies the type of macro instructions, the transmittal mode, 
and type of search to be used with the data set being processed. The operand can be 
coded in any of the combinations shown above; the following describes the characters 
that can be coded. 

The following characters can be specified only when the data set is being created 
(load mode) or additional records are being added to the end of the data set (resume 
load): 

PL 

Specifies that PUT macro instructions are used in the locate transmittal mode; the 
system provides the problem program with the address of a buffer containing the 
data to be written into the data set. 

PM 

Specifies that PUT macro instructions are used in the move transmittal mode; the 
system moves the data to be written from the problem program work area to the 
buffer being used. 

The following characters can be specified only when the data set is being processed 
(scan mode) or when records in an ISAM data set are being updated in place: 

GL 

Specifies that GET macro instructions are used in the locate transmittal mode; the 
system provides the problem program with the address of a buffer containing the 
logical record read. 

GM 

Specifies that GET macro instructions are used in the move mode; the system 
moves the logical record from the buffer to the problem program work area. 



I 



K 



Specifies that actual device addresses (MBBCCHHR) are used to search for a 
record (or the first record) to be read. 



Specifies that a key or key class is used to search for a record (or the first record) 
to be read. 

PU 

Specifies that PUTX macro instructions are used to return updated records to the 
data set. 

S 

Specifies that SETL macro instructions are used to set the beginning location for 
processing the data set. 

Source: The MACRF operand must be coded in the DCB macro instruction. 
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NTM=absexp (maximum value is 99) 

The NTM operand specifies the number of tracks to be created in a cylinder index 
before a higher-level index is created. If the cylinder index exceeds this number, a 
master index is created by the system; if a master index exceeds this number, the next 
level of master index is created. The system creates up to three levels of master 
indexes. The NTM operand is ignored unless the master index option (OPTCD=M) is 
selected. 

Source: When an ISAM data set is being created, the NTM operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
ISAM data set is being processed, master index information is supplied to the data 
control block from the data set label, and the NTM operand must be omitted. 

OPTCD=[I][L][M][R][U][W][Y] 

The OPTCD operand specifies the optional services performed by the system when an 
ISAM data set is being created. The following describes the characters that can be 
specified (these characters can be specified in any order, and no commas are allowed 
between characters): 

I 

Specifies that the system uses the independent overflow areas to contain overflow 
records. Note that it is only the use of the allocated independent overflow area that 
is optional. Under certain conditions, the system designates an overflow area that 
was not allocated for independent overflow by the problem program. See 
"Allocating Space for an Indexed Sequential Data Set" in OS/VS2 MVS Data 
Management Services Guide. 

L 

Specifies that the data set will contain records flagged for deletion. A record is 
flagged for deletion by placing a hexadecimal value of 'FF' in the first data byte. 
Records flagged for deletion remain in the data set until the space is required for 
another record to be added to the track. Records flagged for deletion are ignored 
during sequential retrieval of the ISAM data set (QISAM, scan mode). This option 
cannot be specified for blocked fixed-length records if the relative key position is 
zero (RKP=0), or it cannot be specified for variable-length records if the relative 
key position is four (RKP=4). 

When an ISAM data set is being processed with BISAM, a record with a duplicate 
key can be added to the data set (WRITE KN macro instruction), only when 
OPTCD=L has been specified and the original record (the one whose key is being 
duplicated) has been flagged for deletion. 

M 

Specifies that the system creates and maintains a master index(es) according to the 
number of tracks specified in the NTM operand. 

R 

Specifies that the system places reorganization statistics in the DCBRORG1, 
DCBRORG2, and DCBRORG3 fields of the data control block. The problem 
program can analyze these statistics to determine when to reorganize the data set. 
If the OPTCD operand is omitted completely, the reorganization statistics are 
automatically provided. However, if the OPTCD operand is supplied, OPTCD =R 
must be specified to obtain the reorganization statistics. 
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u 

Specifies that the system accumulates track index entries in storage and writes them 
as a group for each track of the track index. OPTCD=U can be specified only for 
fixed-length records. The entries are written in fixed-length unblocked format. 

W 

Specifies that the system performs a validity check on each record written. 

Y 

Specifies that the system uses the cylinder overflow area(s) to contain overflow 
records. If OPTCD=Y is specified, the CYLOFL operand specifies the number of 
tracks to be used for the cylinder overflow area. The reserved cylinder overflow 
area is not used unless OPTCD=Y is specified. 

Source: When an ISAM data set is created, the OPTCD operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before an OPEN macro instruction is issued to open the data set. 
However, all optional services must be requested from the same source. When an 
existing ISAM data set is processed, the optional service information is supplied to the 
data control block from the data set label, and the OPTCD operand should be 
omitted. 

RECFM={V[B]|F[B]} 

The RECFM operand specifies the format and characteristics of the records in the 
data set. If the RECFM operand is omitted, variable-length records (unblocked) are 
assumed. The following describes the characters that can be specified: 

B 

Specifies that the data set contains blocked records. 

F 

Specifies that the data set contains fixed-length records. 

V 

Specifies that the data set contains variable-length records. 

Source: When an ISAM data set is created, the RECFM operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before an OPEN macro instruction is issued to open the data set. 
When an existing ISAM data set is processed, the record format information is 
supplied by the data set label, and the RECFM operand should be omitted. 

RKP=absexp 

The RKP operand specifies the relative position of the first byte of the key within 
each logical record. For example, if RKP=9 is specified, the key starts in the tenth 
byte of the record. The delete option (OPTCD=L) cannot be specified if the relative 
key position is the first byte of a blocked fixed-length record or the fifth byte of a 
variable-length record. If the RKP operand is omitted, RKP=0 is assumed. 

If unblocked fixed-length records with RKP=0 are used, the key is not written as a 
part of the data record, and the delete option can be specified. If blocked fixed-length 
records are used, the key is written as part of each data record; either RKP must be 
greater than zero or the delete option must not be used. 

If variable-length records (blocked or unblocked) are used, RKP must be four or 
greater if the delete option is not specified; if the delete option is specified, RKP must 
be specified as five or greater. The four additional bytes allow for the block descriptor 
word in variable-length records. 
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Source: When an ISAM data set is created, the RKP operand can be supplied in the 
DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the RKP information is supplied by the data set 
label and the RKP operand should be omitted. 

SYNAD=relexp 

The SYNAD operand specifies the address of the error analysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 

The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered; if the error 
analysis routine continues processing, the results may be unpredictable. 

For additional information on error analysis routine processing for indexed sequential 
data sets, see OS/VS2 MVS Data Management Services Guide. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error analysis routine 
address at any time. 
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DCB — Construct a Data Control Block (QSAM) 

The data control block for the queued sequential access method (QSAM) is constructed 
during assembly of the problem program. The DSORG and MACRF operands must be 
coded in the DCB macro instruction, but the other DCB operands can be supplied, to the 
data control block, from other sources. Each DCB operand description contains a 
heading, "Source." The information under this heading describes the sources from which 
the operand can be supplied. 

Before a DCB macro instruction for creating or processing a QSAM data set is coded, 
the following characteristics of QSAM data sets should be considered. 

• All record formats can be processed. 

• Automatic blocking and deblocking of records is provided. 

• Automatic buffer control is provided; this function fills input buffers when they are 
empty and writes output buffers when they are full. 

• A logical record interface is provided; a GET macro instruction retrieves the next 
sequential logical record from the input buffer, and a PUT macro instruction places 
the next sequential logical record in the output buffer. 

• I/O operations are synchronized automatically. 

• Four transmittal modes (move, locate, data, and substitute) are provided. These 
transmittal modes provide flexibility in buffer management and data movement 
between buffers. 

• Keys for direct-access device records cannot be read or written using QSAM. 

• Specifying the DEVD operand in the DCB macro instruction can cause the program to 
be device-dependent. 

These characteristics of queued sequential access method data sets are described in more 
detail in OS/VS2 MVS Data Management Services Guide. 

For information on additional operands for the DCB macro for. the 3890, see IBM 
3890 Document Processor Machine and Programming Description. 
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The DCB macro for QSAM is written as follows: 



[symbol] 


DCB 


[BFALN={F|D}] 
[BFTEK={S|E|A}] 
[BLKSIZE= absexp] 
[BUFCB= relexp] 
[BUFL= absexp] 
[BUFNO=afeexp] 
[BUFOFF={afoexp | L}] 
[DDNAME= symbol]^ 

[DEVD= {DA} 

{TA 

[,DEN={0|1|2|3|4}] 
[,TRTCH={C|E|ET|T}] } 

{PT 
[,CODE= {A | B | C | F 1 1 1 N | T}] } 

{PR 

[,PRTSP={0|1|2|3}] } 

{PC 

[,MODE=[C | E][R]] 
[,STACK={1|2}] 
[,FUNC= {I | P | PW[XT] | R | RP[D] | 

RW[T] | RWP[XT][D] | W[T]}] 

{RD 

[,MODE=[C|E][0|R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | 

RW[T] | RWP[XT][D] | W[T]}]}] 

DSORG={PS|PSU} 
[EODAD= relexp] 
[EROPT={ACC | SKP | ABE}] 
[EXLST= relexp] 
[\MECl,= {absexp | X}] 

MACRF= {(G{M | L | T | D}[C]) } 

{(P{M|L|T|D}[C]) } 

{(G{M | L | T | D}[C],P{M | L | T | D}[C])} 



^This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 

Continued on next page. 
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[OPTCD= {B } 






{T } 






(U[C] } 






{C[T][B][U] } 






{H[Z][B] } 






{J[C][U] } 






{W[C][T][B][U]} 






{Z[C][T][B][U] } 






{Q[C][B][T|Z]}] 






[RECFM={U[T][A|M] } 






{V[B[S][T]|S[T]|T][A|M]} 






1D[B][A] } 






{F[B|S|T|BS|BT][A|M]}] 






[SYNAD= relexp ] 



The following describes the operands that can be specified in the DCB macro instruction 
for a QSAM data set: 

BFALN={F|D} 

The BFALN operand specifies the boundary alignment of each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides double word 
alignment for each buffer. 

If the data set being created or processed contains ASCII tape records with a block 
prefix, the block prefix is entered at the beginning of the buffer, and data alignment 
depends on the length of the block prefix. For a description of how to specify the 
block prefix length, refer to the BUFOFF operand. 

The following describes the characters that can be specified: 

F 

Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 

D 

Specifies that each buffer is on a doubleword boundary. 

If the BUILD macro instruction is used to construct the buffer pool, the problem 
program must control buffer alignment. 

Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied from the same source. 

BFTEK={S|E|A} 

The BFTEK operand specifies the buffering technique that is used when the QSAM 
data set is created or processed. If the BFTEK operand is omitted, simple buffering is 
assumed. The following describes the characters that can be specified: 

S 

Specifies that simple buffering is used. 
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E 

Specifies that exchange buffering is used. Exchange buffering can be used only with 
record formats (RECFM operand) F, FB, FBS, or FS; the track-overflow feature 
cannot be used with exchange buffering. If exchange buffering is used with ASCII 
tape records, the BUFOFF operand must be zero (no block prefix). Note: 
BFTEK=E is ignored by VS2 systems. 

A 

Specifies that a logical record interface is used for variable-length spanned records. 
When BFTEK=A is specified, the Open routine acquires a record area equal to the 
length specified in the LRECL field plus 32 additional bytes for control 
information. When a logical record interface is requested, the system uses the 
simple buffering technique. 

To use the simple or exchange buffering technique efficiently, the user should be 
familiar with the four transmittal modes for QSAM and the buffering techniques as 
described in OS/ VS2 MVS Data Management Services Guide. 

Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 

BLKSlZE=absexp (maximum value is 32,760) 

The BLKSIZE operand specifies the length, in bytes, of a data block for fixed-length 
records, or it specifies the maximum length, in bytes, of a data block for 
variable-length or undefined-length records. 

The actual value that can be specified in the BLKSIZE operand depends on the device 
type and record format being used. Device capacity is shown in Appendix C of this 
publication. For additional information about device capacity, refer to OS/VS2 MVS 
Data Management Services Guide. For direct-access devices when the 
track-overflow feature is used or variable-length spanned records are being processed, 
the BLKSIZE operand can be up to the maximum value. For other record formats 
used with direct-access devices, the value specified in the BLKSIZE operand cannot 
exceed the capacity of a single track. 

Since QSAM provides a logical record interface, the device capacities shown in 
Appendix C also apply to a maximum length logical record. One exception to the 
device capacity for a logical record is the size of variable-length spanned records. 
Their length can exceed the value specified in the BLKSIZE operand (see the 
description of the LRECL operand). 

If fixed-length records are used for a SYSOUT data set, the value specified in the 
BLKSIZE operand must be an integral multiple of the value specified in the LRECL 
operand; otherwise, the system will adjust the block size downward to the nearest 
multiple. If the records are unblocked fixed-length records, the value specified in the 
BLKSIZE operand must equal the value specified in the LRECL operand if the 
LRECL operand is specified. 

If variable-length records are used, the value specified in the BLKSIZE operand must 
include the data length (up to 32,756 bytes) plus four bytes required for the block 
descriptor word (BDW). For format-D variable-length records, the minimum 
BLKSIZE is 1 8 bytes and the maximum is 2,048 bytes. 

If ASCII tape records with a block prefix are processed, the value specified in the 
BLKSIZE operand must also include the length of the block prefix. 
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If variable-length spanned records are used, the value specified in the BLKSIZE 
operand can be the best one for the device being used or the processing being done. 
When unit record devices (card or printer) are used, the system assumes records are 
unblocked; the value specified for the BLKSIZE operand is equivalent to one print 
line or one card. A logical record that spans several blocks is written one segment at a 
time. 

If undefined-length records are used, the problem program can insert the actual record 
length into the DCBLRECL field. See the description of the LRECL operand. 

Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

BUFCB=relexp 

The BUFCB operand specifies the address of the buffer pool control block 
constructed by a BUILD or BUILDRCD macro instruction. 

If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block, and the BUFCB operand should be omitted. 

Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 

B\J¥h=absexp (maximum value is 32,760) 

The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is acquired automatically. The system acquires buffers with a 
length equal to the value specified in the BLKSIZE operand if the BUFL operand is 
omitted; if the problem program requires larger buffers, the BUFL operand is 
required. If the data set is for card image mode, the BUFL operand is specified as 160 
bytes. The description of the DEVD operand contains a description of card image 
mode. 

If the data set contains ASCII tape records with a block prefix, the value specified in 
the BUFL operand must also include the length of the block prefix. 

If the buffer pool is constructed by a BUILD, BUILDRCD, or GETPOOL macro 
instruction, the BUFL operand is not required. 

Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 

B\JFNO=absexp (maximum value is 255) 

The BUFNO operand specifies the number of buffers in the buffer pool constructed 
by a BUILD or BUILDRCD macro instruction, or it specifies the number of buffers 
to be acquired automatically. If chained scheduling is specified, the value of BUFNO 
determines the maximum number of channel program segments that can be chained 
and must be specified as more than one. If the BUFNO operand is omitted and the 
buffers are acquired automatically, the system acquires three buffers if the device is a 
unit-record device or two buffers for any other device type. For VS2 MVS, the system 
acquires five buffers. 

If the buffer pool is constructed by a GETPOOL macro instruction, the BUFNO 
operand is not required. 

Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 
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DCB— QSAM 

BUFOFF={absexp\L] 

The BUFOFF operand specifies the length, in bytes, of the block prefix used with 
ASCII tape data sets. When QSAM is used to read ASCII tape records, only the data 
portion (or its address) is passed to the problem program; the block prefix is not 
available to the problem program. Block prefixes (except BUFOFF=L) cannot be 
included in QSAM output records. The following can be specified in the BUFOFF 
operand: 

absexp 

Specifies the length, in bytes, of the block prefix. This value can be from to 99 
for an input data set. The value must be for writing an output data set with 
fixed-length or undefined-length records. 

L 

Specifies that the block prefix is 4 bytes long and contains the block length. 
BUFOFF=L is used when format-D records (ASCII) are processed. QSAM uses 
the four bytes as a block-descriptor word (BDW). For further information on this 
operand, see "Variable-Length Records — Format D" in OS/ VS2 MVS Data 
Management Services Guide. 

Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. BUFOFF =absexp can also be 
supplied by the label of an existing data set; BUFOFF=L cannot be supplied by the 
label of an existing data set. 

DDNAME=symbol 

The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 

Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 

DEVD={DA | TA | PT | PR | PC | RD}[, options] 

The DEVD operand specifies the device type on which the data set can or does reside. 
The device types above are shown with the optional operand(s) that can be coded 
when a particular device is used. The devices are listed in order of 
device-independence. For example, if DEVD=DA is coded in a DCB macro 
instruction (or the DEVD operand is omitted, which causes a default to DA), the data 
control block constructed during assembly could later be used for any of the other 
devices, but if DEVD=RD is coded, the data control block can be used only with a 
card reader or card reader punch. Unless you are certain that device interchangeability 
is not required, you should either code DEVD=DA or omit the operand and allow it to 
default to DA. 

If system input is directed to an intermediate storage device, the DEVD operand is 
omitted, and the job control language for the problem program must designate the 
system input to be used. Similarly, if system output is directed to an intermediate 
storage device, the DEVD operand is omitted, and the job control language for the 
problem program must designate the system output to be used. 

If DEVD=PT is coded, the DCB macro should not be coded within the first 8 bytes 
of addressability for the control section (CSECT). If DEVD = PR, PC, or RD is 
coded, the DCB macro should not be coded within the first 16 bytes of addressability 
for the control section. 
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The DEVD operand is discussed below according to individual device type: 

DEVD=DA 

Specifies that the data control block can be used for a direct-access device (or any 
of the other device types described following DA). 

DEVD=TA 

[,DEN={0|1|2|3|4}] 

[,TRTCH={C|E|ET|T}] 

Specifies that the data control block can be used for a magnetic tape data set (or 

any of the other device types described following TA). If TA is coded, the following 

optional operands can be coded: 

DEN={0|1|2|3|4} 

The DEN operand specifies the recording density in the number of bits-per-inch 
per track as shown in the following chart: 



Recording Density 




DEN 7-TrackTape 


9-Track Tape 


200 


— 


1 556 


— 


2 800 


800 (NRZI) 1 


3 — 


1600 (PE)2 


4 — 


6250 (GCRP 



' NRZI is for non-return-to-zero inverted mode 

^ PE is for phase encoded mode 

■* GCR is for group coded recording mode 

Note: Specifying DEN=0 for a 7-track 3420 tape attached to a 3803-1 will 
result in 556 bits-per-inch recording, but corresponding messages and tape labels 
will indicate 200 bits-per-inch recording density. 

If the DEN operand is not supplied by any source, the highest applicable density 
is assumed. 

TRTCH= {C | E | ET | T} 

The TRTCH operand specifies the recording technique for 7-track tape. One of 
the above character combinations can be coded. If the TRTCH operand is 
omitted, odd parity with no translation or conversion is assumed. The following 
describes the characters that can be specified: 



C 



E 



Specifies that the data-conversion feature is used with odd parity and no 
translation. 



Specifies even parity with no translation or conversion. 



ET 

Specifies even parity with BCDIC to EBCDIC translation required, but no 
data-conversion feature. 

T 

Specifies that BCDIC to EBCDIC translation is required with odd parity and 
no data-conversion feature. 
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DCB— QSAM 

DEVD=PT 

[,CODE={A|B|C|F|I|N|T}] 

Specifies that the data control block is used for a paper tape device (or any of the 

other devices following PT). If PT is coded, the following optional operand can be 

coded: 

CODE={A|B|C|F|I|N|T} 

The CODE operand specifies the code in which the data was punched. The 
system converts these codes to EBCDIC code. If the CODE operand is not 
supplied by any source, CODE=I is assumed. The following describes the 
characters that can be specified: 



B 



Specifies 8-track tape in ASCII code. 



Specifies Burroughs 7-track tape. 



Specifies National Cash Register 8-track tape. 



Specifies Friden 8-track tape. 



Specifies IBM BCD perforated tape and transmission code with 8-tracks. 

N 

Specifies that no conversion is required. 

T 

Specifies Teletype 1 5-track tape. 

DEVD=PR 

[,PRTSP={0|1|2|3}] 

Specifies that the data control block is used for an on-line printer (or any of the 
other device types following PR). If PR is coded, the following optional operand 
can be coded: 

PRTSP={0|1|2|3} 

The PRTSP operand specifies the line spacing on the printer. This operand is not 
valid if the RECFM operand specifies either machine (RECFM=M) or ANSI 
(RECFM=A) control characters. If the PRTSP operand is not specified from 
any source, one is assumed. The following describes the characters that can be 
specified: 







Specifies that spacing is suppressed (no space). 



Specifies single-spacing. 



Specifies double-spacing (one blank line between printed lines). 



Specifies triple-spacing (two blank lines between printed lines). 



^Trademark of Teletype Corporation. 
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DEVD=PC 

[,MODE=[C|E][R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]}] 

Specifies that the data control block is used for a card punch (or any of the other 

device types following PC). If PC is coded, the following optional operands can be 

specified: 

MODE=[C|E][R] 

The MODE operand specifies the mode of operation for the card punch. If the 
MODE operand is omitted, E is assumed. The following describes the characters 
that can be specified: 



C 



E 
R 



Specifies that the cards are punched in card image mode. In card image mode, 
the 12 rows in each card column are punched from two consecutive bytes of 
virtual storage. Rows 12 through 3 are punched from the low-order 6 bits of 
one byte, and row 4-9 are punched from the 6 low-order bits of the following 
byte. 

Specifies that cards are punched in EBCDIC code. 

Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 



Note: If the MODE operand is specified in the DCB subparameter of a DD 
statement, either C or E must be specified if R is specified. 

STACK={1|2} 

The STACK operand specifies the stacker bin into which the card is placed after 
punching is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 

1 

Specifies stacker number 1 . 

2 

Specifies stacker number 2. 

FUNC= {I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]} 

The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 



D 



I 



Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output punch portion of a read and punch or 
read, punch, and print operation. 

Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 
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p 

R 
T 



DCB— QSAM 

Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 

Specifies that the data set is for reading cards. 

Specifies that the two-line option is used. The two-line print option allows 
two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 

W 

Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 

X 

Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 

Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 

DEVD=RD 

[,MODE=[C|E][0|R]] 

[,STACK={1|2}] 

[,FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]}] 

RD 

Specifies that the data control block is used with a card reader or card read punch. 
If RD is specified, the data control block cannot be used with any other device 
type. When RD is coded, the following optional operands can be specified: 

MODE=[C|E][0|R] 

The MODE operand specifies the mode of operation for the card reader. The 
following describes the characters that can be specified: 

C 

Specifies that the cards to be read are in card image mode. In card image 
mode, the 12 rows of each card column are read into two consecutive bytes of 
virtual storage. Rows 12 through 3 are read into the low-order 6 bits of one 
byte, and rows 4 through 9 are read into the low-order 6 bits of the following 
byte. 



Specifies that the cards to be read contain data in EBCDIC code. 

Specifies that the program runs in optical mark read mode (3505 card reader). 

R 

Specifies that the program runs in read-column-eliminate mode (3505 card 
reader and 3525 card punch, read feature). 
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Note: If the MODE operand for a 3505 or 3525 is specified in the DCB 
subparameter of a DD statement, either C or E must be specified if R or O is 
specified. 

STACK={1 |2} 

The STACK operand specifies the stacker bin into which the card is placed after 
reading is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 

1 

Specifies stacker number 1 . 

2 

Specifies stacker number 2. 

FUNC={I | P | PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]} 

The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 



D 



I 

P 

R 

T 



Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output punch portion of a read and punch or 
read, punch, and print operation. 

Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 

Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 



Specifies that the data set is for reading cards. 

Specifies that the two-line option is used. The two-line print option allows 
two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 

W 

Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 

X 

Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer" 
output data set from the 3525 punch output data set. 

Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 
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DCB— QSAM 

Source: The DEVD operand can be supplied only in the DCB macro instruction. 
However, the optional operands can be supplied in the DCB macro instruction, the 
DCB subparameter of a DD statement, or by the problem program before 
completion of the data control block exit routine. 

DSORG={PS|PSU} 

The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following can be specified in the DSORG operand: 

PS 

Specifies a physical sequential data set. 

PSU 

Specifies a physical sequential data set that contains location-dependent 
information. 

Source: The DSORG operand must be coded in the DCB macro instruction. 

EODAD=relexp 

The EODAD operand specifies the address of the routine given control when the end 
of an input data set is reached. Control is given to this routine when a GET macro 
instruction is issued and there are no additional records to be retrieved. If the record 
format is RECFM=FS or FBS the end-of-data condition is sensed when file mark is 
read or if more data is requested after reading a truncated block. If the end of the data 
set has been reached but no EODAD address has been supplied to the data control 
block, or if a GET macro instruction is issued after an end-of-data exit is taken, the 
task is abnormally terminated. For additional information on the EODAD routine, see 
OS/VS2 MVS Data Management Services Guide. 

Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set has been reached. 

EROPT={ACC | SKP | ABE } 

The EROPT operand specifies the action taken by the system when an uncorrectable 
input/output data validity error occurs and no error analysis (SYNAD) routine 
address has been provided, or it specifies the action taken by the system after the 
error analysis routine has returned control to the system with a RETURN macro 
instruction. The specified action is taken for input operations or for output operations 
to a printer. 

Uncorrectable input/output errors resulting from channel operations or direct-access 
operations that make the next record inaccessible cause the task to be abnormally 
terminated regardless of the action specified in the EROPT operand. 

ACC 

Specifies that the problem program accepts the block causing the error. This action 
can be specified when a data set is opened for INPUT, RDBACK, UPDAT, or 
OUTPUT (OUTPUT applies to printer data sets only). 

SKP 

Specifies that the block that caused the error is skipped. Specifying SKP also causes 
the buffer associated with the data block to be released. This action can be 
specified when a data set is opened for INPUT, RDBACK, or UPDAT. 
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ABE 

Specifies that the error results in the abnormal termination of the task. This action 
can be specified when the data set is opened for INPUT, OUTPUT, RDBACK, or 
UPDAT. 

If the EROPT operand is omitted, the ABE action is assumed. 

Source: The EROPT operand can be specified in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program at any time. The 
problem program can also change the action specified at any time. 

EXLST=relexp 

The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program requires additional processing for 
user labels, user totaling, data control block exit routine, end-of -volume, block count 
exits, to define a forms control buffer (FCB) image, use the JFCBE exit (for the 3800 
printer), or to use the DCB ABEND exit for ABEND condition analysis. 

Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit routine processing, refer to 
OS/VS2 MVS Data Management Services Guide. 

Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program any time before the exit is required by the problem program. 

LRECL={ absexp | X} 

The LRECL operand specifies the length, in bytes, for fixed-length logical records, or 
it specifies the maximum length, in bytes for variable-length or undefined-length 
(output only) logical records. The value specified in the LRECL operand cannot 
exceed the value specified in the BLKSIZE operand except when variable-length 
spanned records are used. 

For fixed-length records that are unblocked, the value specified in the LRECL 
operand must be equal to the value specified in the BLKSIZE operand. For blocked 
fixed-length records, the value specified in the LRECL operand must be evenly 
divisible into the value specified in the BLKSIZE operand. 

For variable-length logical records, the value specified in the LRECL operand must 
include the maximum data length (up to 32,752) plus four bytes for the 
record-descriptor word (RDW). 

For undefined-length records, the problem program must insert the actual logical 
record length into the DCBLRECL field before writing the record, or the maximum 
length record will be written. 

For variable-length spanned records, the logical record length (LRECL) can exceed 
the value specified in the BLKSIZE operand, and a variable-length spanned record 
can exceed the maximum block size (32,760 bytes). When the logical record length 
exceeds the maximum block size, LRECL=X must be specified and GET or PUT 
locate mode must be used. 

Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 
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DCB— QSAM 

MACRF= {(G{M | L | T | D}[ C ]) } 

{(P{M|L|T|D}[C]) } 

KG{M|L|T|D}[C],P{M|L|T|D}[C])} 

The MACRF operand specifies the type of macro instructions (GET, PUT or PUTX, 
CNTRL, RELSE, and TRUNC) and the transmittal modes (move, locate, data, and 
substitute) that are used with the data set being created or processed. The operand 
can be coded in any of the combinations shown above; the following describes the 
characters that can be coded: 

C 

Specifies that the CNTRL macro instruction is used with the data set. If the 
CNTRL macro instruction is specified, the data set should be for a card reader 
(stacker selection) or printer (carriage and spacing control). The CNTRL option 
can be specified with GET in the move mode only. 

D 

Specifies that the data transmittal mode is used (only the data portion of a record is 
moved to or from the work area). Data mode is used only with variable-length 
spanned records. 

G 

Specifies that GET macro instructions are used. Specifying G also provides the 
routines that allow the problem program to issue RELSE macro instructions. 

L 

Specifies that the locate transmittal mode is used; the system provides the address 
of the buffer containing the data. 

M 

Specifies that the move transmittal mode is used; the system moves the data from 
the buffer to the work area in the problem program. 

P 

Specifies that PUT or PUTX macro instructions are used. Specifying P also 
provides the routines that allow the problem program to issue TRUNC macro 
instructions. 

T 

Specifies that the substitute transmittal mode is used; the system substitutes a 
buffer for a work area contained in the problem program. 

Note: For data sets on paper tape that are processed by QSAM, only MACRF=(GM) 
can be specified. 

Source: The MACRF operand can be supplied only in the DCB macro instruction. 



Macro Instruction Descriptions 103 



Page of GC26-3873-0 

As Updated March 30, 1979 

By TNL GN26-0941 



OPTCD= {B 
{T 

{U[C] 

{C[T][B][U] 

(H[Z][B] 

(J[C][U] 

{W[C][T][B][U] 

{Z[C][T][B][U] 

{Q[C][B][T|Z] 

The OPTCD operand specifies the optional services used with the QSAM data set. 
Two of the optional services, OPTCD=B and OPTCD=H, cannot be specified in the 
DCB macro instruction. They are requested in the DCB subparameter of a DD 
statement. Since all optional services codes must be supplied by the same source, the 
OPTCD operand must be omitted from the DCB macro instruction if either of these 
options is requested in a DD statement. The following describes the characters that 
can be specified: 

C 

Requests that chained scheduling be used. OPTCD =C cannot be specified when 
either BFTEK=A or BFTEK=R is specified for the same data control block. Aviso, 
chained scheduling cannot be specified for associated data sets or printing on 
a 3525. For 5740-AM3 chained scheduling is ignored for direct access devices. 

Note: Chained scheduling is used whether requested or not, except where it is not 
allowed. See OS/VS2 MVS Data Management Services Guide for conditions 
where chained scheduling is not allowed. 



J 



T 



Specifies that the first data byte in the output data line will be a 3800 table 
reference character. This table reference character selects a particular character 
arrangement table for the printing of the data line and can be used singularly or in 
conjunction with ANSI or machine control characters. This option is valid only for 
the 3800 Printing Subsystem. For information on the table reference character and 
character arrangement table, see IBM 3800 Printing Subsystem Programmer's 
Guide. 

Requests that ASCII tape records in an input data set be converted to EBCDIC 
code when the input record has been read, or an output record in EBCDIC code be 
converted to ASCII code before the record is written. For further information on 
this conversion, see "Variable-Length Records — Format D" in OS/VS2 MVS 
Data Management Services Guide. To determine the ASCII to EBCDIC or 
EBCDIC to ASCII translation codes, see System/ 3 70 Reference Summary, 
GX20-1850. 

Requests the user totaling facility. If this facility is requested, the EXLST operand 
should specify the address of an exit list to be used. T cannot be specified for a 
SYSIN or SYSOUT data set. 
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DCB— QSAM 

U 

Specified only for a printer with the universal-character-set feature or the 3800 
Printing Subsystem. This option unblocks data checks (permits them to be 
recognized as errors) and allows analysis by the appropriate error analysis routine 
(SYNAD routine). If the U option is omitted, data checks are not recognized as 
errors. 

For the IBM Mass Storage System (MSS) : U requests window processing to reduce 
the amount of staging space required to process large sequential data sets on MSS. 
DSORG must specify physical sequential, allocation must be in cylinders, and type 
of I/O accessing must be either INPUT only or OUTPUT only. 

W 

Specifies that the system performs a validity check for each record written on the 
direct-access device being used. 

Z 

For magnetic tape, input only, the Z option requests the system to shorten its 
normal error recovery procedure to consider a data check as a permanent I/O error 
after five unsuccessful attempts to read a record. This option is available only if it is 
selected when the operating system is generated. OPTCD=Z is used when a tape is 
known to contain errors and there is no need to process every record. The error 
analysis routine (SYNAD) should keep a count of permanent errors and terminate 
processing if the number becomes excessive. 

For direct-access devices only, the Z option requests the system to use the search 
direct option to accelerate the input operations for a data set. OPTCD=Z cannot 
be specified with spanned, standard, or track-overflow records. 

5740-AM3 only: For direct-access devices only, the Z option is ignored. 

Note: The following describes the optional services that can be specified in the DCB 
subparameter of a DD statement. If either of these options is requested, the complete 
OPTCD operand must be supplied in the DD statement. 

B 

If OPTCD =B is specified in the DCB subparameter of a DD statement, it forces 
the end-of -volume (EOV) routine to disregard the end-of-file recognition for 
magnetic tape. When this occurs, the EOV routine uses the number of volume 
serial numbers to determine end of file. For an input data set on a standard labeled 
(SL or AL) tape, the EOV routine will treat EOF labels as EOV labels until the 
volume serial list is exhausted. When all the volumes have been read, control is 
passed to the user's end-of-data routine. This option allows SL or AL tapes to be 
read out of volume sequence or to be concatenated to another tape using one DD 
statement. 

H 

If OPTCD=H is specified in the DCB subparameter of a DD statement, it specifies 
that the DOS/OS interchange feature is being used with the data set. 
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RECFN= {U[ T ][ A | M ] } 

|V[B[S][T]|S[T]|T][A|M]} 

|D[B][A] } 

{F[B|S|T|BS|BT][A|M] } 

The RECFM operand specifies the record format and characteristics of the data set 
being created or processed. All record formats can be used in QSAM. The following 
describes the characters that can be specified: 

A 

Specifies that the records in the data set contain American National Standards 
Institute (ANSI) control characters. Refer to Appendix E for a description of 
control characters. 



B 
D 

F 
M 

S 



Specifies that the data set contains blocked records. 

Specifies that the data set contains variable-length ASCII tape records. See 
OPTCD=Q and the BUFOFF operand for a description of how to specify ASCII 
data sets. 

Specifies that the data set contains fixed-length records. 

Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. RECFM=M cannot be 
used with ASCII data sets. 



T 



For fixed-length records, S specifies that the records are written as standard blocks; 
the data set does not contain any truncated blocks or unfilled tracks, with the 
exception of the last block or track in the data set. Do not code S for fixed-length 
records to retrieve records from a data set that was created using a RECFM other 
than standard. 

For variable-length records, S specifies that a record can span more than one block. 
If spanned records are used, exchange buffering (BFTEK=E) cannot be specified. 

Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track and the 
remainder of the record on the following track (if required). Chained scheduling 
(OPTCD=C) and exchange buffering (BFTEK=E) cannot be used if the 
track-overflow feature is used. 

U 

Specifies that the data set contains undefined-length records. 

V 

Specifies that the data set contains variable-length records. 

Notes: 

• RECFM=V cannot be specified for a card reader data set or an ASCII tape data 
set. 

• RECFM= VS or VBS cannot be specified for a SYSIN data set. 
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DCB— QSAM 

Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 

SYNAD=relexp 

The SYNAD operand specifies the address of the error analysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 

The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction that uses the address in register 14 to return control to 
the system. 
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DCB— QSAM 

If the error condition was the result of a data-validity error, the control program takes 
the action specified in the EROPT operand; otherwise, the task is abnormally 
terminated. The control program takes these actions when the SYNAD operand is 
omitted or when the error analysis routine returns control. 

Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCBD — Provide Symbolic Reference to Data Control 
Blocks (BDAM, BISAM, BPAM, BSAM, QISAM, and 
QSAM) 

The DCBD macro instruction is used to generate a dummy control section that provides 
symbolic names for the fields in one or more data control blocks. The names and 
attributes of the fields appear as part of the description of each data control block in 
Appendix F of this publication. Attributes of the symbolically named fields in the dummy 
section are the same as the fields in the data control blocks, with the exception of fields 
containing 3-byte addresses. The symbolically named fields containing 3-byte addresses 
have length attributes of four and are aligned on fullword boundaries. 

The labels generated by the DCBD macro should not be defined within a user program. 
The macro labels are structured as DCBxxxxx where DCB are the first three characters 
and xxxxx are 1 -5 alphameric characters. 

The name of the dummy control section generated by a DCBD macro instruction is 
IHADCB. The use of any of the symbolic names provided by the dummy section must be 
preceded by a USING instruction specifying IHADCB and a dummy section base 
register (which contains the address of the actual data control block). The DCBD macro 
instruction can only be issued once within any assembled module; however, the resulting 
symbolic names can be used for any number of data control blocks by changing the 
address in the dummy section base register. The DCBD macro instruction can be coded 
at any point in a control section; if coded at any point other than at the end of a control 
section; however, the control section must be resumed by coding a CSECT instruction. 

The DCBD macro instruction is written as follows: 



b 


DCBD 


[DSORG=({GS | 

[BS][,DA][,IS][,LR][,PO][,PS][,QS]})] 

[,DEVD=([DA][,PC][,PR][,PT][,RD][,TA] 
[,MR][,OR])] 



DSORG=({GS | [BS][,DA][,IS][,LR][,PO][,PS][,QS]}) 

The DSORG operand specifies the types of data control blocks for which symbolic 
names are provided. If the DSORG operand is omitted, the DEVD operand is ignored, 
and symbolic names are provided only for the "foundation block" portion that is 
common to all data control blocks. One or more of the following pairs of characters 
can be specified (each pair of characters must be separated by a comma): 



BS 



Specifies a data control block for a sequential data set and basic access method. 



DA 



Specifies a data control block for a direct data set. 



IS 



Specifies a data control block for an indexed sequential data set. 



LR 



Specifies a dummy section for the logical record length field (DCBLRECL) only. 



PO 



PS 



Specifies a data control block for a partitioned data set. 

Specifies a data control block for a sequential data set. PS includes both BS and 
QS. 
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DCBD 

QS 

Specifies a data control block for a sequential data set and queued access method. 

GS 

Specifies a data control block for graphics; this operand cannot be used in 
combination with any of the above. 

DEVD=[DA][,PC][,PR][,PT][,RD][,TA][,MR][,OR] 

The DEVD operand specifies the types of devices on which the data set can reside. If 
the DEVD operand is omitted and a sequential data set is specified in the DSORG 
operand, symbolic names are provided for all of the device types listed below. One or 
more of the following pairs of characters can be specified; each pair of characters 
must be separated by a comma: 

DA 

Direct-access device 

PC 

Online punch 

PR 

Online printer 

PT 

Paper tape 

RD 

Online card reader or read punch feed 

TA 

Magnetic tape 

MR 

Magnetic character reader 

OR 

Optical character reader 
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ESETL — End Sequential Retrieval (QISAM) 



The ESETL macro instruction ends the sequential retrieval of data from an indexed 
sequential data set and causes the buffers associated with the specified data control block 
to be released. An ESETL macro instruction must separate SETL macro instructions 
issued for the same data control block. 

The ESETL macro instruction is written as follows: 



[symbol] 


ESETL 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block opened for 
the indexed sequential data set being processed. 
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FEOV— Force End of Volume (BSAM and QSAM) 

The FEOV macro instruction causes the system to assume an end-of-volume condition, 
and causes automatic volume switching. Volume positioning for magnetic tape can be 
specified by the option operand. If no option is coded, the positioning specified in the 
OPEN macro instruction is used. Output labels are created as required and new input 
labels are verified. The standard exit routines are given control as specified in the data 
control block exit list. For BSAM, all input and output operations must be tested for 
completion before the FEOV macro instruction is issued. The end-of-data-set (EODAD) 
routine is given control if an input FEOV macro instruction is issued for the last volume 
of an input data set. FEOV is ignored if issued for a SYSIN or SYSOUT data set. 

The FEOV macro instruction is written as follows: 



[symbol] 


FEOV 


deb address 
[,REWIND | ,LEAVE] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for an 
opened sequential data set. 

The following operands request optional services: 

REWIND 

Requests that the system position the tape at the load point regardless of the direction 
of processing. 

LEAVE 

Requests that the system position the tape at the logical end of the data set on that 
volume; this option causes the tape to be positioned at a point after the tapemark that 
follows the trailer labels. Note that multiple tape units must be available to achieve 
this positioning. If only one tape unit is available, its volume is rewound and unloaded. 

Note: If an FEOV macro is issued for a multivolume data set with spanned records 
that is being read using QSAM, errors may occur when the next GET macro is issued 
following an FEOV macro if the first segment on the new volume is not the first 
segment of a record. The errors include duplicate records, program checks in the user 
program, and invalid input from the variable spanned data set. 
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FIND — Establish the Beginning of a Data Set Member 
(BPAM) 

The FIND macro instruction causes the system to use the address of the first block of a 
specified partitioned data set member as the starting point for the next READ macro 
instruction for the same set. All previous input and output operations that specified the 
same data control block must have been tested for completion before the FIND macro 
instruction is issued. 

The FIND macro instruction is written as follows: 



[symbol] 


FIND 


deb address 

,{name address, D\ relative address list,C} 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened partitioned data set being processed. 

name address — RX-Type Address, (2-12), or (0) 

The name address operand specifies the address of an 8-byte field that contains the 
data set member name. The name must start in the first byte and be padded on the 
right (if necessary) to complete the eight bytes. 

D 

Specifies that only a member name has been supplied, and the access method must 
search the directory of the data set indicated in the data control block to find the 
location of the member. 

relative address list — RX-Type Address, (2-12), or (0) 

The relative address list operand specifies the address of the area that contains the 
relative address (TTRK) for the beginning of a data set member. The relative address 
can be a list entry completed by using a BLDL macro instruction for the data set 
being processed, or the relative address can be supplied by the problem program. 

C 

Specifies that a relative address has been supplied, and no directory search is required. 
The relative address supplied is used directly by the access method for the next input 
operation. 



Completion Codes 



For relative address list, C, when the system returns control to the problem program, 
the low-order byte of register 15 contains the following return code; the three high-order 
bytes of register 15 are set to zero. 

relative address list, C 

00 — At all times. If the relative address is in error, execution of the next CHECK macro 
instruction causes control to be passed to the error analysis (SYNAD) routine. 

For name address, D, when the system returns control to the problem program, the 
low-order byte of register 1 5 contains a return code and the low-order byte of register 
contains a reason code. The three high-order bytes of both registers are set to zero. 

name address, D 

Hexadecimal Codes 
Return (15) Reason (0) Meaning 

Successful execution. 

Name not found. 

Permanent I/O error found during directory search. 

Insufficient virtual storage available. 



00 


00 


04 


00 


08 


00 


08 


04 
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FREEBUF — Return a Buffer to a Pool (BDAM, BISAM, 
BPAM, and BSAM) 

The FREEBUF macro instruction causes the system to return a buffer to the buffer pool 
assigned to the specified data control block. The buffer must have been acquired using a 
GETBUF macro instruction. 

The FREEBUF macro instruction is written as follows: 



[symbol] 


FREEBUF 


deb address 
, register 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for an 
opened data set to which the buffer pool has been assigned. 

register — (2-12) 

The register operand specifies one of registers 2 through 1 2 that contains the address 
of the buffer being returned to the buffer pool. 
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FREEDBUF — Return a Dynamically Obtained Buffer 
(BDAM and BISAM) 

The FREEDBUF macro instruction causes the system to return a buffer to the buffer 
pool assigned to the specified data control block. The buffer must have been acquired 
through dynamic buffering; that is, by coding 'S' for the area address operand in the 
associated READ macro instruction. 

Note: A buffer acquired dynamically can also be released by a WRITE macro 
instruction; refer to the description of the WRITE macro instruction for BDAM or 
BISAM. 

The FREEDBUF macro instruction is written as follows: 



[symbol] 


FREEDBUF 


decb address 

,{K|D} 
,dcb address 



decb address — RX-Type Address, (2-12), or (0) 

The decb address operand specifies the address of the data event control block 
(DECB) used or created by the READ macro instruction that acquired the buffer 
dynamically. 



K 



Specifies that BISAM is being used. 



D 

Specifies that BDAM is being used. 

deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened data set being processed. 
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FREEPOOL— Release a Buffer Pool (BDAM, BISAM, 
BPAM, BSAM, QISAM, and QSAM) 



The FREEPOOL macro instruction causes an area of storage, previously acquired for a 
buffer pool for a specified data control block, to be released. The area must have been 
acquired either automatically (except when dynamic buffer control is used) or by the 
execution of a GETPOOL macro instruction. For queued access methods, the 
FREEPOOL macro instruction must not be issued until after a CLOSE macro 
instruction has been issued for all the data control blocks using the buffer pool. For basic 
access methods, the FREEPOOL macro instruction can be issued as soon as the buffers 
are no longer required. A buffer pool should be released only once, regardless of the 
number of data control blocks sharing the buffer pool. 

The FREEPOOL macro instruction is written as follows: 



[symbol] 


FREEPOOL 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of a data control block to which the 
buffer pool has been assigned. 
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GET — Obtain Next Logical Record (QISAM) 



The GET macro instruction causes the system to retrieve the next record. Control is not 
returned to the problem program until the record is available. 

The GET macro instruction is written as follows: 



[symbol] 


GET 


deb address 
[,area address] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened input data set being retrieved. 

area address — RX-Type Address, (2-12), or (0) 

The area address operand specifies the storage address into which the system is to 
move the record (move mode only). Either the move or locate mode can be used with 
QISAM, but they must not be mixed within the specified data control block. The 
following describes operations for move and locate modes: 

Locate Mode: If the locate mode has been specified in the data control block, the area 
address operand must be omitted. The system returns the address of the buffer 
segment containing the record in register 1 . 

Move Mode: If the move mode has been specified in the data control block, the area 
address operand must specify the address in the problem program into which the 
system will move the record. If the area address operand is omitted, the system 
assumes that register contains the area address. When control is returned to the 
problem program, register contains the area address, and register 1 contains the 
address of the data control block. 

Notes: 

1. The end-of -data-set (EODAD) routine is given control if the end of the data set is 
reached; the data set may be closed if processing is completed, or an ESETL macro 
must be issued before a SETL macro to continue further input processing. 

2. The error analysis (SYNAD) routine is given control if the input operation could not 
be completed successfully. The contents of the general registers when control is given 
to the SYNAD routine are described in Appendix A. 

3. When the key of an unblocked fixed-length record is retrieved with the data, the 
address of the key is returned as follows (see the SETL macro instruction): 

Locate Mode: The address of the key is returned in register 0. 

Move Mode: The key appears in front of the record in your buffer area. 

4. If a GET macro instruction is issued for a data set and the previous request issued for 
the same data set was an OPEN, ESETL, or unsuccessful SETL (no record found), a 
SETL B (key and data) is invoked automatically, and the first record in the data set is 
returned. 
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GET— Obtain Next Logical Record (QSAM) 



The GET macro instruction causes the system to retrieve the next record. Various modes 
are available and are specified in the DCB macro instruction. In the locate mode, the 
GET macro instruction locates the next sequential record or record segment to be 
processed. The system returns the address of the record in register 1 and places the 
length of the record or segment in the logical-record-length (DCBLRECL) field of the 
data control block. The user can process the record within the input buffer or move the 
record to a work area. 

In the move mode, the GET macro instruction moves the next sequential record to the 
user's work area. This work area must be big enough to contain the largest logical record 
of the data set and its record-descriptor word (variable-length records). The system 
returns the address of the work area in register 1. (This feature provides compatibility 
with the substitute mode GET.) The record length is placed in the DCBLRECL field. 
The move mode can be used only with simple buffering. 

In the data mode, which is available only for variable-length spanned records, the GET 
macro instruction moves only the data portion of the next sequential record to the user's 
work area. The TYPE=P operand cannot be used with data mode. 

In the substitute mode, the GET macro instruction transfers ownership of the next 
sequential record in a data set from the system to the user. In return, the ownership of a 
work area is transferred from the user to the system for future use as an input buffer. 
There is no movement of data. The address of an input buffer containing the record is 
returned to the user in register 1 after the instruction is executed. The system returns the 
record length in the DCBLRECL field. For undefined-length records, the DCBLRECL 
field is equal to the BLKSIZE field for chained scheduling. The substitute mode can be 
used only with exchange buffering and cannot be used with variable-length records. The 
TYPE=P operand cannot be used with substitute mode. 

If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. When translation is requested, all QSAM records 
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically 
translated from ASCII code to EBCDIC code as soon as the input buffer is full. For 
translation to occur correctly, all input data must be in ASCII code. 

The GET macro instruction is written as follows: 



[symbol] 


GET 


{deb address \pdab address} 
[,area address] 
[,TYPE=P] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened input data set being retrieved. 

pdab address — RX-Type Address, (2-12), or (1) 

The pdab address operand specifies the address of the parallel data access block for 
the opened input data sets from which a record is to be retrieved. When pdab address 
is used, TYPE=P must be coded. 

area address — RX-Type Address, (2-12), or (0) 

The area address operand specifies the address of an area into which the system is to 
move the record (move or data mode), or it specifies the address of an area to be 
exchanged for the buffer containing the record (substitute mode). The move, locate, 
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data, or substitute mode can be used with QSAM, but they must not be mixed within 
the specified data control block. If the area address operand is omitted in the move, 
data, or substitute mode, the system assumes that register contains the area address. 
The following describes the operation of the four modes: 

Locate Mode: If the locate mode has been specified in the data control block, the area 
address operand must be omitted. The system returns the address of the beginning 
buffer segment containing the record in register 1 . If the data set is open for 
RDBACK, register 1 will point to the end of the buffer segment rather than the 
beginning. 

When retrieving variable-length spanned records, the records are obtained one 
segment at a time. The problem program must retrieve additional segments by issuing 
subsequent GET macro instructions, except when a logical record interface is 
requested (by specifying BFTEK=A in the DCB macro instruction or by issuing a 
BUILDRCD macro instruction.) In this case, the control program retrieves all record 
segments and assembles the segments into a complete logical record. The system 
returns the address of this record area in register 1. To process a record when the 
logical record length is greater than 32,756 bytes, LRECL=X must be specified in the 
data control block, and the problem program must assemble the segments into a 
complete logical record. 

Move Mode: If the move mode has been specified in the data control block, the area 
address operand specifies the beginning address of an area in the problem program 
into which the system will move the record. If the data set is open for RDBACK, the 
area address operand specifies the ending address of an area in the problem program. 

For variable-length spanned records, the system constructs the record-descriptor word 
in the first four bytes of the area and assembles one or more segments into the data 
portion of the logical record; the segment descriptor words are removed. 

Data Mode: If the data mode has been specified in the data control block (data mode 
can be specified for variable-length spanned records only), the area address operand 
specifies the address of the area in the problem program into which the system will 
move the data portion of the logical record; a record-descriptor word is not 
constructed when data mode is used. The TYPE=P operand cannot be used with data 
mode. 

Substitute Mode: If the substitute mode is specified in the data control block, the area 
address operand specifies the address of an area in the problem program that will be 
exchanged for the buffer containing the record. The system returns the address of the 
buffer containing the record in register 1. The TYPE=P operand cannot be used with 
substitute mode. 

Note: If spanned records extend across volumes, errors may occur when using the 
GET macro if a volume which begins with a middle or last record segment is mounted 
first, or if an FEOV macro is issued followed by a GET macro. QSAM cannot begin 
reading from the middle of the record. (This applies to move mode, data mode, and 
locate mode if logical record interface is specified.) 

TYPE=P— Coded as shown 

The TYPE=P and pdab address operands are used to retrieve a record from a queue 
of input data sets that have been opened. The open and close routines add and delete 
DCB addresses in the queue. The DCB from which a record is retrieved can be 
located from information in the PDAB. For this purpose, the formatting macro, 
PDABD, should be used. 
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GET— QSAM 

GET Routine Exits 

The end-of-data-set (EODAD) routine is given control if the end of the data set is 
reached; the data set must be closed. Issuing a GET macro instruction in the EODAD 
routine results in abnormal termination of the task. 

The error analysis (SYNAD) routine is given control if the input operation could not be 
completed successfully. The contents of the general registers when control is given to the 
SYNAD routine are described in Appendix A. 
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GETBUF— Obtain a Buffer (BDAM, BISAM, BPAM, 
and BSAM) 

The GETBUF macro instruction causes the control program to obtain a buffer from the 
buffer pool assigned to the specified data control block and to return the address of the 
buffer in a designated register. The BUFCB field of the data control block must contain 
the address of the buffer pool control block when the GETBUF macro instruction is 
issued. The system returns control to the instruction following the GETBUF macro 
instruction. The buffer obtained must be returned to the buffer pool using a FREEBUF 
macro instruction. 

The GETBUF macro instruction is written as follows: 



[symbol] 


GETBUF 


deb address 
, register 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block that contains 
the buffer pool control block address. 

register — (2-12) 

The register operand specifies one of the registers 2 through 12 in which the system is 
to place the address of the buffer obtained from the buffer pool. If no buffer is 
available, the contents of the designated register are set to zero. 
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GETPOOI^-Build a Buffer Pool (BDAM, BISAM, 
BPAM, BSAM, QISAM, and QSAM) 

The GETPOOL macro instruction causes a buffer pool to be constructed in a storage 
area acquired by the system. The system places the address of the buffer pool control 
block in the BUFCB field of the data control block. The GETPOOL macro instruction 
must be issued either before an OPEN macro instruction is issued or during the data 
control block exit routine for the specified data control block. 

The GETPOOL macro instruction is written as follows: 



[symbol] 


GETPOOL 


deb address 

,{ number of buffers , buffer length | (0)} 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block to which the 
buffer pool is assigned. Only one buffer pool can be assigned to a data control block. 

number of buffers — symbol, decimal digit, absexp, or (2-12) 

The number-of-buffers operand specifies the number of buffers in the buffer pool up 
to a maximum of 255. 

buffer length — symbol, decimal digit, absexp, or (2-12) 

The buffer length operand specifies the length, in bytes, or each buffer in the buffer 
pool. The" value specified for the buffer length must be a double word multiple; 
otherwise the system rounds the value specified to the next higher doubleword 
multiple. The maximum length that can be specified is 32,760 bytes. For QSAM, the 
buffer length must be at least as large as the value specified in the block size 
(DCBBLKSI) field in the data control block. 

(0) — Coded as shown 

The number of buffers and buffer length can be specified in general register 0. If (0) 
is coded, register must contain the binary values for the number of buffers and 
buffer length as shown in the following illustration: 



Bits: 



Register 












Number of Buffers 


Buffer Length 







15 


16 




31 



Byte: 



The following illustration shows the format of the buffer pool. The buffer pool and the 
associated storage area are released by issuing a FREEPOOL macro instruction after 
issuing a CLOSE macro instruction for the data set indicated in the specified data control 
block. 



Area 
Address 



BUFAD 



Address of First 

Available 

Buffer 



Reserved 

for 

Flags 



BUFNO 



Number 

of 

Buffers 



4 5 

-Buffer Pool Control Block- 
(8 bytes) 



BUFL 



Length 
of Each 
Buffer 



Buffer 



-Buffer Length- 



Buffer 



-Buffer Length — ► 



-Area Length. 



Area Length= (Buffer Length) x (Number of Buffers) +8 
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NOTE — Provide Relative Position (BPAM and 
BSAM — Tape and Direct Access Only) 



The NOTE macro instruction causes the system to return the relative position of the last 
block read from or written into a data set. All input and output operations using the same 
data control block must be tested for completion before the NOTE macro instruction is 
issued. 

The capability of using the NOTE macro instruction is automatically provided when a 
partitioned data set is used (DSORG=PO or POU), but when a sequential data set 
(BSAM) is used, the use of NOTE/POINT macro instructions must be indicated in the 
MACRF operand of the DCB macro instruction. The relative position, in terms of the 
current volume, is returned in register 1 as follows: 

Magnetic Tape: The block number is in binary, right-adjusted in register 1 with 
high-order bits set to zero. Do not use a NOTE macro instruction for tapes without 
standard labels when: 

• The data set is opened for RDBACK (specified in the OPEN macro instruction) or 

• The DISP parameter of the DD statement for the data set specifies DISP=MOD. 
Direct- Access Device: TTRz format, where: 

TT is a 2-byte relative track number. 

R is a 1-byte block (record) number on the track indicated by TT. 

z is a byte set to zero. 

The NOTE macro instruction cannot be used for SYSIN or SYSOUT data sets. 

Note: When a direct-access device is being used, the amount of remaining space on the 
track is returned in register if a NOTE macro instruction follows a WRITE macro 
instruction; if a NOTE macro instruction follows a READ or POINT macro instruction, 
the track capacity of the direct-access device is returned in register 0. 

The NOTE macro instruction is written as follows: 



[symbol] 


NOTE 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block opened for 
the partitioned or sequential data set being processed. 
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OPEN— Logically Connect a Data Set (BDAM, BISAM, 
BPAM, BSAM, QISAM, and QSAM) 

The OPEN macro instruction causes the specified data control block(s) to be completed 
and the data set(s) identified in the data control block(s) to be prepared for processing. 
Input labels are analyzed and output labels are created. Control is given to exit routines 
as specified in the data control block exit list. The processing method (option 1 ) is 
designated to provide correct volume positioning for the data set and define the 
processing mode (INPUT, OUTPUT, etc.) for the data set(s). Final volume positioning 
(when volume switching occurs) can be specified (option 2) to override the positioning 
implied by the DD statement DISP parameter. Option 2 applies only to volumes in a 
multivolume data set other than the last volume. Any number of data control block 
addresses and associated options may be specified in the OPEN macro instruction. 

If associated data sets for a 3525 card punch are being opened, all associated data sets 
must be open before an I/O operation is initiated for any of the data sets. For a 
description of associated data sets, refer to OS/VS2 MVS Data Management Services 
Guide. 

To support DEB validity checking in OS/VS, an OPEN macro instruction must be issued 
for every data extent block (DEB) created. 

The standard form of the OPEN macro instruction is written as follows (the list and 
execute forms are shown following the description of the standard form): 



[ symbol ] 


OPEN 


(deb address ,[( opt ions)],. ..) 



deb address — A-Type Address or (2-12) 

The deb address operand(s) specifies the address of the data control block(s) for the 
data set(s) to be prepared for processing. 

options 

The options operands shown in the following illustration indicate the volume 
positioning available based on the device type and access method being used. If option 
1 is omitted, INPUT is assumed. If option 2 is omitted, DISP is assumed. Option 1 
must be coded if option 2 is coded. Option 2 is ignored for SYSIN and SYSOUT data 
sets. Options 1 and 2 are ignored for BISAM and QISAM (in the scan mode), and the 
data control block indicates the operation. OUTPUT or OUTIN must be specified 
when creating a data set. 
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DEVICE TYPE 






ACCESS 












METHOD 


Magnetic tape 




Direct access 




Other Types 




Option 1 


Option 2 


Option 1 


Option 2 


Option 1 


QSAM 


[INPUT ] 


LREREAD] 


[INPUT ] 


LREREAD] 


[INPUT ] 


| 


[EXTEND] 


[,LEAVE ] 


[EXTEND] 


[,LEAVE ] 


[EXTEND] 




[OUTPUT ] 


LDISP ] 


[OUTPUT] 


LDISP ] 


[OUTPUT] 




[RDBACK] 




[UPDAT ] 






BSAM 


[INPUT ] 


[,REREAD] 


[INPUT ] 


[,REREAD] 


[INPUT ] 


| 


[EXTEND] 


[,LEAVE ] 


[EXTEND] 


[,LEAVE ] 


[EXTEND] 


1 


[OUTINX ] 


[,DISP ] 


[OUTINX] 


LDISP ] 


[OUTPUT] 




[OUTPUT ] 




[OUTPUT] 








[INOUT ] 




[INOUT ■]• 








[OUTIN ] 




[OUTIN ] 








[RDBACK] 




[UPDAT ] 






QISAM 


— 


— 


[OUTPUT] 


— 


— 


1 (Load Mode) 






[EXTEND] 






BPAM, 


— 


— 


[INPUT ] 


— 


— 


BDAM 






[OUTPUT] 
[UPDAT ] 







Option 2 



The following describes the options shown in the preceding illustration. All option 
operands are coded as shown. 

Option 1 Meaning 

EXTEND (VS2.03.808 only) The data set is treated like an OUTPUT data set 

except that records will be added to the end of the data set regardless of 
what was specified on the DISP parameter of the DD statement. 

INPUT Input data set. 

INOUT The data set is first used for input and, without reopening, it is used as 

an output data set. The data set is processed as INPUT for a SYSIN 
data set or if LABEL=(,„IN) is specified in the DD statement. 

OUTPUT Output data set (for BDAM, OUTPUT is equivalent to UPDAT). 

OUTIN The data set is first used for output and, without reopening, it is used as 

an input data set. The data set is processed as OUTPUT for a SYSOUT 
data set or if LABEL=(,„OUT) is specified in the DD statement. 

OUTINX (VS2.03.808 only) The data set is treated like an OUTIN data set 

except that records will be added to the end of the data set regardless of 
what was specified on the DISP parameter of the DD statement. 

RDBACK Input data set, positioned to read backward. 

UPDAT Data set to be updated in place or, for BDAM, blocks are to be updated 

or added. 
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OPEN 



Option 2 
LEAVE 



Meaning 



REREAD 



DISP 



Positions the current tape volume to the logical end of the data set when 
volume switching occurs. If processing was forward, the volume is 
positioned to the end of the data set; if processing was backwards 
(RDBACK), the volume is positioned to the beginning of the data set. 

Positions the current tape volume to reprocess the data set when volume 
switching occurs. If processing was forward, the volume is positioned to 
the beginning of the data set; if processing was backwards (RDBACK), 
the volume is positioned to the end of the data set. 

Specifies that a tape volume is to be disposed of in the manner implied 
by the DD statement associated with the data set. Direct-access volume 
positioning and disposition are not affected by this parameter of the 
OPEN macro instruction. There are several dispositions that can be 
specified in the DISP parameter of the DD statement; DISP can be 
PASS, DELETE, KEEP, CATLG, or UNCATLG. This option has 
significance at the time an end-of-volume condition is encountered only 
when DISP is PASS. The end-of-volume condition may result from the 
issuance of an FEOV macro instruction or may be the result of reaching 
the end of a volume. 

If DISP is PASS in the DD statement, the tape will be spaced forward to 
the end of the data set on the current volume. 

If any DISP option is coded in the DD statement (except when DISP is 
PASS), the resultant action at the time an end-of-volume condition 
arises depends on (1) how many tape units are allocated to the data set 
and (2) how many volumes are specified for the data set in the DD 
statement. This is determined by the UNIT and VOLUME parameters 
of the DD statement associated with the data set. If the number of 
volumes is greater than the number of units allocated, the current 
volume will be rewound and unloaded. If the number of volumes is less 
than or equal to the number of units, the current volume is merely 
rewound. 

Note: When the DELETE option is specified, the system waits for the completion of the 
rewind operation before it continues processing subsequent reels of tape. 

The LEAVE and REREAD options are meaningless except for magnetic tape and 
CLOSE TYPE=T. Any other options specified for CLOSE TYPE=T besides LEAVE 
and REREAD will be treated as LEAVE during execution. 

After the OPEN macro instruction has been executed, bit 3 of the DCBOFLGS field in 
the data control block is set to 1 if the data control block has been opened successfully, 
but is set to if the data control block has not been opened successfully. 
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The following errors cause the results indicated: 
Error Result 



Attempting to open a data control 
block that is already open. 

Attempting to open a data control 
block when the deb address 
operand does not specify the 
address of a data control block. 

Attempting to open a DCB for a 
printer with the UCS feature and 
an error occurred when attempting 
to block or unblock data checks 
(specified by the presence or absence 
of OPTCD=U in the DCB macro). 

Attempting to open a data control 
block when a corresponding DD 
statement has not been provided. 



No action. 
Unpredictable. 

Task abnormally terminated. 



A "DD STATEMENT MISSING" message 
is issued. An attempt to use the data 
set causes unpredictable results. 



The last of these errors can be detected by testing bit 3 of the DCBOFLGS field in the 
data control block. Bit 3 is set to in the case of an error and can be tested by the 
sequence: 

TM DCBOFLGS,X'10' 



BZ ERRORRTN 



(Branch to user's error routine) 



Executing the two instructions shown above requires writing a DCBD macro instruction 
in the program, and a base register must be defined with a USING statement before the 
instructions are executed. 
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OPEN — List Form 



The list form of the OPEN macro instruction is used to construct a data management 
parameter list. Any number of operands (data control block addresses and associated 
options) can be specified. 

The list consists of a one-word entry for each DCB in the parameter list; the high-order 
byte is used for the options and the three low-order bytes are used for the DCB address. 
The end of the list is indicated by a one in the high-order bit of the last entry's option 
byte. The length of a list generated by a list form instruction must be equal to the 
maximum length list required by any execute form instruction that refers to the same list. 
A maximum length list can be constructed by one of two methods: 

• Code a list-form instruction with the maximum number of parameters that are 
required by an execute form instruction that refers to the list. 

• Code a maximum length list by using commas in a list-form instruction to acquire a list 
of the appropriate size. For example, coding OPEN (,„„„„),MF=L would provide a 
list of five fullwords (five deb addresses and five options). 

Entries at the end of the list that are not referenced by the execute-form instruction are 
assumed to have been filled in when the list was constructed or by a previous 
execute-form instruction. Before using the execute-form instruction, you may shorten the 
list by placing a one in the high-order bit of the last DCB entry to be processed. 

A zeroed work area on a fullword boundary is equivalent to OPEN 
(,(INPUT,DISP),...),MF=L and can be used in place of a list-form instruction. The 
high-order bit of the last DCB entry must contain a one before this list can be used with 
the execute-form instruction. 

A parameter list constructed by an OPEN, list form, macro instruction can be referred to 
by either an OPEN or CLOSE execute form instruction. 

The description of the standard form of the OPEN macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are completely optional and those required in at least one of 
the pair of list and execute forms. The format description below indicates the optional 
and required operands in the list form only. 

The list form of the OPEN macro instruction is written as follows: 



[symbol] 


OPEN 


( [ deb address ] , [ ( options )],...) 
,MF=L 



deb address — A-Type Address 

MF=L — Coded as shown 

The MF=L operand specifies that the OPEN macro instruction is used to create a 
data management parameter list that is referenced by an execute form instruction. 
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OPEN — Execute Form 



A remote data management parameter list is used in, and can be modified by, the execute 
form of the OPEN macro instruction. The parameter list can be generated by the list 
form of either an OPEN or CLOSE macro instruction. 

The description of the standard form of the OPEN macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands in the execute form only. 

The execute form of the OPEN macro instruction is written as follows: 



[symbol] 


OPEN 


[([deb address ],[( opt ions )], ...)] 
,MF=(E,{^fl/fl management list address | (1)}) 



deb address — RX-Type Address or (2-12) 

MF=(E,{ data management list address | (1)} 

This operand specifies that the execute form of the OPEN macro instruction is used, 
and an existing data management parameter list (created by a list-form instruction) is 
used. The MF= operand is coded as follows: 

E — Coded as shown 

data management list address — RX-Type, (2-12), (1) 
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PDAB — Construct a Parallel Data Access Block (QSAM) 

The PDAB macro instruction is used in conjunction with the GET (TYPE=P) macro 
instruction. It defines an area in the problem program where the Open and Close 
routines build and maintain a queue of DCB address for use by the Get routine. 

The parallel data access block is constructed during the assembly of the problem 
program. The MAXDCB operand must be coded in the PDAB macro instruction because 
it cannot be supplied from any other source. 

Certain data set characteristics prevent a DCB address from being available on the 
queue — see the description of QSAM parallel input processing in OS/VS2 MVS Data 
Management Services Guide. 

The PDAB macro instruction is written as follows: 



[symbol] 


PDAB 


MAXDCB= deb number 



MAXDCB =absexp (maximum value is 32,767) 

Specifies the maximum number of DCBs that you require in the queue for a GET 
request. 

Note: The number of bytes required for PDAB is equal to 24+8 n where n is the 
value of the keyword, MAXDCB. 
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PDABD — Provide Symbolic Reference to a Parallel Data 
Access Block (QSAM) 

The PDABD macro instruction is used to generate a dummy control section that provides 
symbolic names for the fields in one or more parallel data access blocks. The names, 
attributes, and descriptions of the fields appear in Appendix H. 

The name of the dummy control section generated by a PDABD macro instruction is 
IHAPDAB. The use of any of the symbolic names provided by the dummy section 
should be preceded by a USING instruction specifying IHAPDAB and a dummy section 
base register containing the address of the actual parallel data access block. The PDABD 
macro instruction should only be used once within any assembled module; however, the 
resulting symbolic names can be used for any number of parallel data access blocks by 
changing the address in the dummy section base register. The PDABD macro instruction 
can be coded at any point in a control section. If coded at any point other than at the end 
of a control section, the control section must be resumed by coding a CSECT instruction. 

The PDABD macro instruction is written as follows: 



b 


PDABD 


b 
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POINT — Position to a Relative Block (BPAM and 
BSAM — Tape and Direct Access Only) 

The POINT macro instruction causes the system to start processing the next READ or 
WRITE operation at the specified block in the data set on the current volume. All input 
and output operations using the same data control block must have been tested for 
completion before the POINT macro instruction is issued. When processing a data set 
that has been opened for UPDAT, the POINT macro instruction must be followed by a 
READ macro instruction. When processing an output data set, the POINT macro 
instruction must be followed by a WRITE macro instruction prior to closing the data set, 
unless a CLOSE macro instruction (with TYPE=T specified) was issued prior to the 
POINT macro instruction. 

The POINT macro instruction is written as follows: 



[symbol] 


POINT 


deb address 
, block address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened data set that is to be positioned. 

block address — RX-Type Address, (2-12), or (0) 

The block address operand specifies the address of a fullword on a fullword boundary 
containing the relative address of the block in the data set that is to be processed next. 
The relative address is specified as follows: 

Magnetic Tape: The block number is in binary and is right-adjusted in the fullword 
with the high-order bits set to zero; add one if reading tape backward. Do not use the 
POINT macro instruction for tapes without standard labels when: 

• The data set is opened for RDBACK or 

• The DD statement for the data set specifies DISP=MOD. 

If OPTCD=H is indicated in the data control block, the POINT macro instruction can 
be used to perform record positioning on DOS tapes that contain embedded 
checkpoint records. Any embedded checkpoint records that are encountered during 
the record positioning are bypassed and are not counted as blocks spaced over. 
OPTCD=H must be specified in a job control language DD statement. Do not use the 
POINT macro instruction to backspace DOS 7-track tapes that are written in data 
convert mode and that contain embedded checkpoint records. 

Note: When an end-of-data condition is encountered on magnetic tape, you must not 
issue the POINT macro instruction unless you have first repositioned the tape for 
processing within your data set; otherwise, the POINT operation will be unsuccessful. 
(Issuing CLOSE TYPE=T is an easy method to accomplish repositioning in your 
EODAD routine.) 

Direct-Access Device: The fullword specified in the block address operand contains 
the relative track address (in the form TTRz), where: 

TT is a 2-byte relative track number. 

R is a 1 -byte block (record) number on the track indicated by TT. 

z is a byte set to zero; it may also be set to 1 to retrieve the block following the 
TTR block. 
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Note: The first block of a magnetic tape data set is always specified by the 
hexadecimal value 00000001. The first block of a direct-access device data set can be 
specified by either hexadecimal 00000001 or 00000100 (see the previous description 
ofTTRz). 

POINT cannot be used for SYSIN or SYSOUT data sets. 

If the volume cannot be positioned correctly or if the block identification is not of the 
correct format, the error analysis (SYNAD) routine is given control when the next 
CHECK macro instruction is executed. 
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PRTOV — Test for Printer Carriage Overflow (BSAM 
and QSAM — Online Printer and 3525 Card Punch, Print 
Feature) 

The PRTOV macro instruction is used to control the page format for an online printer 
when carriage control characters are not being used or to supplement the carriage control 
characters that are being used. 

The PRTOV macro instruction causes the system to test for an overflow condition on the 
specified channel (either channel 9 or channel 12) of the printer carriage control, and 
either skip the printer carriage to the line corresponding to channel 1 , or transfer control 
to the exit address, if one is specified. Overflow is detected after printing the line that 
follows the line corresponding to channel 9 or channel 12. The PRTOV macro should be 
issued each time you want the system to test for an overflow condition. 

When the PRTOV macro instruction is used with a 3525 card punch, print feature, 
channel 9 or 12 can be tested. If an overflow condition occurs, control is passed to the 
overflow exit routine if the overflow exit address is coded, or a skip to channel 1 (first 
print-line of the next card) occurs. 

When requesting overprinting (for example, to underscore a line), the PRTOV macro 
instruction is issued before the first PUT or WRITE macro instruction only. The PRTOV 
macro instruction should be issued only when the device type is an online printer. 
PRTOV cannot be used to request overprinting on the 3525. Overprinting cannot be 
performed on the 3800. 

The PRTOV macro instruction is written as follows: 



[symbol] 


PRTOV 


deb address 

,{9|12} 

[, overflow exit address] 



deb address — RX-Type Address or (2-12) 

The deb address operand specifies the address of the data control block opened for 
•output to an online printer or 3525 card punch with a print feature. 

9 — Coded as shown 
12 — Coded as shown 

These operands specify which channel is to be tested by the PRTOV macro 
instruction. For an online printer, 9 and 12 correspond to carriage control channels 9 
and 12. For the 3525 card punch, 9 corresponds to print line number 17, and 12 
corresponds to print line number 23. More detail about the card print-line format is 
included in OS and OS/VS Programming Support for the IBM 3505 Card 
Reader and IBM 3525 Card Punch. 

overflow exit address — RX-Type Address or (2-12) 

The overflow exit address operand specifies the address of the user-supplied routine 
to be given control when an overflow condition is detected on the specified channel. If 
this operand is omitted, the printer carriage skips to the first line of the next page or 
the 3525 skips to the first line of the next card before executing the next PUT or 
WRITE macro instruction. 
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When the overflow exit routine is given control, the contents of the registers are as 
follows: 

Register Contents 

and 1 The contents are destroyed. 

2-13 The same contents as before the macro instruction was 

executed. 

14 Return address. 

15 Overflow exit routine address. 
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PUT— Write Next Logical Record (QISAM) 



The PUT macro instruction causes the system to write a record into an indexed 
sequential data set. If the move mode is used, the PUT macro instruction moves a logical 
record into an output buffer from which it is written. If the locate mode is specified, the 
address of the next available output buffer segment is available in register 1 after the 
PUT macro instruction is executed. The logical record can then be constructed in the 
buffer for output as the next record. The records are blocked by the system (if specified 
in the data control block) before being placed in the data set. The system uses the length 
specified in the record length (DCBLRECL) field of the data control block as the length 
of the record currently being written. When constructing blocked variable-length records 
in the locate mode, the problem program may either specify the maximum record length 
once in the DCBLRECL field of the data control block or provide the actual record 
length in the DCBLRECL field before issuing each PUT macro instruction. Use of the 
maximum record length may result in more but shorter blocks, since the system uses this 
length when it tests to see if the next record can be contained in the current block. 

The PUT macro instruction is used to create or extend an indexed sequential data set. To 
extend the data set, the key of any added record must be higher than the highest key 
existing in the data set, and the disposition parameter of the DD card must be specified 
as DISP=MOD. The new records are placed in the prime data space, starting in the first 
available space, until the original space allocation is exhausted. 

To create a data set using previously allocated space, the disposition parameter of the 
DD card must specify DISP=OLD. 

The PUT macro instruction is written as follows: 



[symbol] 


PUT 


deb address 
[,area address] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened ISAM data set. 

area address — RX-Type Address, (2-12), or (0) 

The area address operand specifies the address of the area that contains the record to 
be written (move mode only). Either move or locate mode can be used with QISAM, 
but they must not be mixed within the specified data control block. The following 
describes operations for locate and move modes: 

Locate Mode: If the locate mode is specified in the data control block, the area 
address operand must be omitted. The system returns the address of the next available 
buffer in register 1 ; this is the buffer into which the next record is placed. The record 
is not written until another PUT macro instruction is issued for the same data control 
block. The last record is written when a CLOSE macro instruction is issued to close 
the data set. 

Move Mode: If the move mode has been specified in the data control block, the area 
address operand must specify the address in the problem program that contains the 
record to be written. The system moves the record from the area to an output buffer 
before control is returned. If the area address operand is omitted, the system assumes 
that register zero contains the area address. 



PUT Routine Exit 



The error analysis (SYNAD) routine is given control if the output operation could not be 
completed satisfactorily. The contents of the registers when the error analysis routine is 
given control are described in Appendix A. 
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PUT— Write Next Logical Record (QSAM) 



The PUT macro instruction causes the system to write a record in a sequential data set. 
Various modes are available and are specified in the DCB macro instruction. In the 
locate mode, the address of an area within an output buffer is returned in register 1 after 
the macro instruction is executed. The user should subsequently construct, at this 
address, the next sequential record or record segment. The move mode of the PUT 
macro instruction causes a logical record to be moved into an output buffer. In the data 
mode, which is available only for variable-length spanned records, the PUT macro 
instruction moves only the data portion of the record into one or more output buffers. 
When the substitute mode is specified, the macro transfers ownership of a work area 
containing a record to the control program. In return, the ownership of a buffer segment 
is transferred to the user, for use as a work area. There is no movement of data in 
storage. 

The records are blocked by the control program (as specified in the data control block) 
before being placed in the data set. For undefined-length records, the DCBLRECL field 
determines the length of the record that is subsequently written. For variable-length 
records, the DCBLRECL field is used to locate a buffer segment of sufficient size 
(locate mode), but the length of the record actually constructed is verified before the 
record is written (the output block can be filled to the maximum if, before issuing the 
PUT macro, DCBLRECL is set equal to the record length). For variable-length spanned 
records, the system segments the record according to the record length, buffer length, 
and amount of unused space remaining in the output buffer. The smallest segment 
created will be 5 bytes, 4 for the segment descriptor word plus one byte of data. 

If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. When translation is requested, all QSAM records 
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically 
translated from EBCDIC code to ASCII code. For translation to occur correctly, all 
output data must be in EBCDIC code; any EBCDIC character that cannot be translated 
into an ASCII character is replaced by a substitute character. 

The PUT macro instruction is written as follows: 



[symbol] 


PUT 


deb address 
[,area address] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the data 
set opened for output. 

area address — RX-Type Address, (2-12), or (0) 

The area address operand specifies the address of an area that contains the record to 
be written (move or data mode), or it specifies the address of an area to be exchanged 
for a buffer (substitute mode). The move, locate, data, or substitute mode can be used 

with QSAM, but they must not be mixed within the specified data control block. If the 
area address operand is omitted in the move, data, or substitute mode, the system 
assumes that register zero contains the area address. The following describes the 
operation of the four modes: 

Locate Mode: If the locate mode is specified, the area address operand must be 
omitted. The system returns the address of the next available buffer in register 1 ; this 
is the buffer into which the next record is placed. 



136 OS/VS2 Data Management Macro Instructions 



PUT Routine Exit 



PUT— QSAM 

When variable-length spanned records are used and a record area has been provided 
for a logical record interface (BFTEK=A has been specified in the data control block 
or a BUILDRCD macro instruction has been issued), the address returned in register 
1 points to an area large enough to contain the maximum record size (up to 32,756 
bytes). The system segments the record and writes all segments, providing proper 
control codes for each segment. If, for variable-length spanned records, an area has 
not been provided, the actual length remaining in the buffer will be returned in 
register 0. In this case, it is the user's responsibility to segment the records and process 
them in terms of record segments. The record or segment is not written until another 
PUT macro instruction is issued for the same data control block. The last record is 
written when the CLOSE macro instruction is issued. 

When a PUT macro instruction is used in the locate mode, the address of the buffer 
for the first record or segment is obtained by issuing a PUT macro instruction; QSAM 
returns the address of the buffer, but the record is not written until the next PUT 
macro instruction is issued. 

Move Mode: If the move mode has been specified in the data control block, the area 
address operand specifies the address of the area that contains the record to be 
written. The system moves the record to an output buffer before control is returned. 
The address of the output buffer is returned in register 1 (this action provides 
compatibility with substitute mode operations, and makes it possible for the problem 
program to be used in instances where substitute mode is requested but cannot be 
supported by the system). 

Data Mode: If the data mode is specified in the data control block (data mode can be 
specified for variable-length spanned records only), the area address operand 
specifies the address of an area in the problem program that contains the data portion 
of the record to be written. The system moves the data portion of the record to an 
output buffer before control is returned. The user must place the total data length in 
the DCBPRECL (not DCBLRECL) field of the data control block before the PUT 
macro instruction is issued. 

Substitute Mode: If the substitute mode is specified in the data control block, the area 
address operand specifies the address of an area in the problem program that contains 
the next record to be written. The area is exchanged for an empty buffer. The address 
of the empty buffer is returned in register 1 . 



The error analysis (SYNAD) routine is given control if an output operation could not be 
completed satisfactorily. If the output operation could not be completed satisfactorily, 
the error analysis (SYNAD) routine is given control after the next PUT instruction is 
issued. The contents of the registers when the error analysis routine is given control are 
described in Appendix A. 
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PUTX — Write a Record from an Existing Data Set 
(QISAM and QSAM) 

The PUTX macro instruction causes the control program to return an updated record to 
a data set (QISAM and QSAM) or to write a record from an input data set into an 
output data set (QSAM only). There are two modes of the PUTX macro instruction. The 
output mode (QSAM only) allows writing a record from an input data set on a different 
output data set. The output data set may specify the spanning of variable-length records, 
but the input data set must not contain spanned records. 

The update mode returns an updated record to the data set from which it was read. The 
logical records are blocked by the control program, as specified in the data control block, 
before they are placed in the output data set. The control program uses the length 
specified in the DCBLRECL field as the length of the record currently being stored. 
Control is not returned to the user's program until the control program has processed the 
record. 

For SYSIN or SYSOUT data sets, the PUTX macro instruction can be used only in the 
output mode. 

The PUTX macro instruction is written as follows: 



[symbol] 


PUTX 


deb address 

[> input deb address] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for a data set 
opened for output. 

input deb address — RX-Type Address, (2-12), or (0) 

The input deb address operand specifies the address of a data control block opened 
for input. The PUTX macro instruction can be used for the following modes: 

Output Mode: This mode is used with QSAM only. The input deb address operand 
specifies the address of the data control block opened for input. If this operand is 
omitted, the system assumes that register contains the input deb address. 

Update Mode: The input deb address operand is omitted for update mode. 



PUTX Routine Exit 



The error analysis (SYNAD) routine is given control if the operation is not completed 
satisfactorily. The contents of the registers when the error analysis routine is given 
control are described in Appendix A. 
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READ— Read a Block (BDAM) 



The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. Control may be returned to the problem program before the 
block is retrieved. The input operation must be tested for completion using a CHECK or 
WAIT macro instruction. A data event control block, shown in Appendix A, is 
constructed as part of the macro expansion. 

The standard form of the READ macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 



[symbol] 


READ 


decb name 

*type 

,dcb address 

,{area address | 'S'} 

,{ length |'S'} 

,{key address | 'S' | 0} 

, block address 

[,next address] 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 

0//*—{DI[F|X][R|RU]} 

{DK[F|X][R|RU]} 
The type operand is coded in one of the combinations shown above to specify the 
type of read operation and the optional services performed by the system: 

DI 

Specifies that the data and key, if any, are to be read from a specific device address. 
The device address, which can be designated by any of the three addressing 
methods, is supplied by the block address operand. 

DK 

Specifies that the data (only) is to be read from a device address identified by a 
specific key. The key to be used as a search argument must be supplied in the area 
specified by the key address operand; the search for the key starts at the device 
address supplied in the area specified by the block address operand. The description 
of the DCB macro instruction, LIMCT operand, contains a description of the search. 



X 



Requests that the system provide block position feedback into the area specified by 
the block address operand. This character can be coded as a suffix to DI or DK as 
shown above. 

r 

Requests exclusive control of the data block being read, and it requests that the 
system provide block position feedback into the area specified by the block address 
operand. The descriptions of the WRITE and RELEX macro instructions contain a 
description of releasing a data block that is under exclusive control. This character 
can be coded as a suffix to DI or DK as shown above. 
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R 

Requests that the system provide next address feedback into the area specified by 
the next address operand. When R is coded, the feedback is the relative track 
address of the next data record. This character can be coded as a suffix to DI or DK, 
DIF, DIX, DKF, or DKX as shown above, but it can be coded only for use with 
variable-length spanned records. 

RU 

Requests that the system provide next address feedback into the area specified by 
the next address operand. When RU is coded, the feedback is the relative track 
address of the next capacity record (RO) or data record whichever occurs first. 
These characters can be coded as a suffix to DI, DK, DIF, DIX, DKF, or DKX, but it 
can be coded only for use with variable-length spanned records. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block opened for 
the data set to be read. 

area address — A-Type Address, (2-12), or 'S' 

The area address operand specifies the address of the area into which the data block 
is to be placed. If 'S' is coded instead of an address, dynamic buffering is requested 
(dynamic buffering must also be specified in the MACRF operand of the DCB macro 
instruction). When dynamic buffering is used, the system acquires a buffer and places 
its address in the data event control block. 

length — symbol, decimal digit, absexp, (2-12), or 'S' 

The length operand specifies the number of data bytes to be read up to a maximum of 
32,760. If 'S' is coded instead of a length, the number of bytes to be read is taken 
from the data control block. This operand is ignored if the records are not format-U. 

key address — A-Type Address, (2-12), 'S', or 

The key address operand specifies the address of the area for the key of the desired 
data block. If the search operation is made using a key, the area must contain the key. 
Otherwise, the key is read into the designated area. If the key is read and 'S' was 
coded for the area address, *S' can also be coded for the key address; the key and data 
are read sequentially into the buffer acquired by the system. If the key is not to be 
read, specify instead of an address or *S\ 

block address — A-Type Address or (2-12) 

The block address operand specifies the address of the area containing the relative 
block address, relative track address, or actual device address of the data block to be 
retrieved. The device address of the data block retrieved is placed in this area if block 
position feedback is requested. The length of the area that contains the address 
depends on whether the feedback option (OPTCD=F) has been specified in the data 
control block and if the READ macro instruction requested feedback. 

If OPTCD=F has been specified, feedback (if requested) is in the same form as was 
originally presented by the READ macro instruction, and the field can be either three 
or eight bytes long depending on the type of addressing. 

If OPTCD=F has not been specified, feedback (if requested) is in the form of an 
actual device address, and the field must be eight bytes long. 
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READ— BDAM 

next address — A-Type Address or (2-12) 

The next address operand specifies the address of the storage area where the system 
places the relative address of the next record. The length operand must be specified as 
'S'. When the next address operand is specified, an R or RU must be added to the 
type operand (for example, DIR or DIRU). The R indicates that the next address 
returned is the next data record. RU indicates that the next address returned is for the 
next data or capacity record, whichever occurs first. The next address operand can be 
coded only for use with variable-length spanned records. 
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READ— Read a Block of Records (BISAM) 



The READ macro instruction causes an unblocked record, or a block containing a 
specified logical record, to be retrieved from a data set. The block is placed in a 
designated area of storage, and the address of the logical record is placed in the data 
event control block. The data event control block is constructed as part of the macro 
expansion and is described in Appendix A. 

Control may be returned to the problem program before the block is retrieved. The input 
operation must be tested for completion using a WAIT or CHECK macro instruction. 

The standard form of the READ macro instruction is written as follows for BISAM (the 
list and execute forms are shown following the descriptions of the standard form) : 



[symbol] 


READ 


decb name 

,type 

,dcb address 

,{area address | 'S'} 

,{ length |'S'} 

,key address 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 

type — {K | KU} 

The type operand is coded as shown to specify the type of read operation: 



K 



Specifies normal retrieval. 



KU 

Specifies that the record retrieved is to be updated and returned to the data set; the 
system saves the device address to be returned. 

When an ISAM data set is being updated with a READ KU macro instruction and 
a WRITE K macro instruction, both the READ and WRITE macro instructions 
must refer to the same data event control block. This update operation can be 
performed by using a list-form instruction to create the list (data event control 
block) and by using the execute form of the READ and WRITE macro instructions 
to refer to the same list. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened data set to be read. 

area address — A-Type Address, (2-12), or 'S' 

The area address operand specifies the address of the area into which the data block 
is placed. The first sixteen bytes of this area are used by the system and do not 
contain information from the data block. The area address must specify a different 
area than the key address. Dynamic buffering is specified by coding 'S' instead of an 
address; the address of the acquired storage area is returned in the data event control 
block. Indexed sequential buffer and work area requirements are described in 
OS/VS2 MVS Data Management Services Guide. 

length — symbol, decimal digit, absexp, (2-12), or *S' 

The length operand specifies the number of bytes to be read up to a maximum of 
32,760. If *S' is coded instead of a length, the number of bytes to be read is taken 
from the count field of the record; for blocked records, 'S' must be coded. 
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READ— -BISAM 

key address — A-Type Address or (2-12) 

The key address operand specifies the address of the area in the problem program 
containing the key of a logical record in the block that is to be retrieved. When the 
input operation is completed, the storage address of the logical record is placed in the 
data event control block. The key address must specify a different area than the area 
address. 
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READ— Read a Block (BPAM and BSAM) 



The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. Control may be returned to the problem program before the 
block is retrieved; The input operation must be tested for completion using a CHECK 
macro instruction. A data event control block, shown in Appendix A, is constructed as 
part of the macro expansion. 

If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro 
instruction must refer to the same data event control block. Refer to the list form of the 
READ or WRITE macro instruction for a description of how to construct a data event 
control block; refer to the execute form of the READ or WRITE macro instruction for a 
description of how to modify an existing data event control block. 

For information on additional operands for the READ macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275. 

For information on additional operands for the READ macro instruction for the 3886, 
see OS/VS IBM 3886 Optical Character Reader Model 1 Reference. 

The standard form of the READ macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form instructions) : 



[ symbol ] 


READ 


decb name 

,type 

,dcb address 

y area address 

I length |,'S'] 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 

type— {SF|SB} 

The type operand is coded as shown to specify the type of read operation: 

SF 

Specifies normal, sequential, forward retrieval. 

SB 

Specifies a read backward operation; this operand can be specified only for 
magnetic tape with format-F or format-U records. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened data set to be read. 

area address — A-Type Address or (2-12) 

The area address operand specifies the address of the problem program area into 
which the record is placed. When a READ SB macro instruction is issued, the area 
address must be the address of the last byte of the area into which the record is read. 
If the data set contains keys, the key is read into the buffer followed by the data. 

length — symbol, decimal digit, absexp, (2-12), or 'S' 

The length operand specifies the number of data bytes to be read, to a maximum of 
32,760. If the data is translated from ASCII code to EBCDIC code, the maximum 
number of bytes that can be read is 2048. A number can be coded only for format-U 
records. The number of bytes to be read is taken from the data control block if 'S' is 
coded instead of a number. (This operand is ignored for format-F or format-V 
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READ— BPAM and BSAM 

records.) For format-D records only, the length of the record just read is automatically 
inserted into the DCBLRECL field by the check routine if BUFOFF=(L) is not 
specified in the data control block. 
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READ — Read a Block (Offset Read of Keyed BDAM 
Data Set Using BSAM) 

The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. The data set is a BDAM data set and its record format is 
unblocked variable-length spanned records. BFTEK=R must be specified in the data 
control block. Control may be returned to the problem program before the block is 
retrieved. The input operation must be tested for completion using a CHECK macro 
instruction. A data event control block, shown in Appendix A, is constructed as part of 
the macro expansion. 

The standard form of the READ macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 



[symbol] 


READ 


decb name 

,SF 

,dcb address 

,area address 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 

SF 

Specifies normal, sequential, forward retrieval. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened BDAM data set to be read. 

area address — A-Type Address or (2-12) 

The area address operand specifies the address of the area into which the record is 
placed. 

When a spanned BDAM data set is created with keys, only the first segment of a record 
has a key; successive segments do not. When a spanned record is retrieved by the READ 
macro instruction, the system places a segment in a designated area addressed by the 
area address operand. The problem program must assemble all the segments into a 
logical record. Since only the first segment has a key, the successive segments are read 
into the designated area offset by key length to ensure that the block-descriptor word 
and the segment-descriptor word are always in the same relative position. 
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READ — List Form 



The list form of the READ macro instruction is used to construct a data management 
parameter list in the form of a data event control block (DECB). Refer to Appendix A 
for a description of the various fields of the DECB for each access method. 

The description of the standard form of the READ macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of 'S' when 
coded for the area address, length, and key address operands. For each access method, 
'S' can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the list form only. 

The list form of the READ macro instruction is written as follows: 



[symbol] 


READ 


decb name 
,type 

.[deb address] 
.[area address | 'S'] 
^length |<S'] 
.[key address | 'S'] 
.[block address] 
.[next address] 
,MF=L 



decb name — symbol 

type — Code one of the types shown in the standard form 

deb address — A-Type Address or 'S' 

area address — A-Type Address or *S' 

length — symbol, decimal digit, absexp, or *S' 

key address — A-Type Address or *S' 

block address — A-Type Address 

next address — A-Type Address 

MF=L — Coded as shown 

The MF=L operand specifies that the READ macro instruction is used to create a 
data event control block that can be referenced by an execute-form instruction. 
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READ — Execute Form 



A remote data management parameter list (data event control block) is used in, and can 
be modified by, the execute form of the READ macro instruction. The data event control 
block can be generated by the list form of either a READ or WRITE macro instruction. 

The description of the standard form of the READ macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of 'S' when 
coded for the area address, length, and key address operands. For each access method, 
'S' can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the execute form only. 

The execute form of the READ macro instruction is written as follows: 



[ symbol ] 


READ 


decb address 

sype 

,[dcb address] 
,[area address | 'S'] 
,[lengthVS>] 
,[ key address \ 'S'] 
\block address] 
,[next address] 
,MF=E . 



decb address — RX-Type Address or (2-12) 

type — Code one of the types shown in the standard form 

deb address — RX-Type Address or (2-12) 

area address — RX-Type Address, (2-12), or 'S' 

length — symbol, decimal digit, absexp, (2-12), or 'S' 

key address — RX-Type Address, (2-12), or 'S' 

block address — RX-Type Address, or (2-12) 

next address — RX-Type Address or (2-12) 

MF=E — Coded as shown 

The MF=E operand specifies that the execute form of the READ macro instruction is 
used, and that an existing data event control block (specified in the decb address 
operand) is used by the access method. 
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RELEX — Release Exclusive Control (BDAM) 



The RELEX macro instruction causes release of a data block from exclusive control. The 
block must have been requested in an earlier READ macro instruction which specified 
either DIX or DKX. 

Note: A WRITE macro instruction that specifies either DIX or DKX can also be used to 
release exclusive control. 

The RELEX macro instruction is written as follows: 



[symbol] 


RELEX 


D 

, deb address 
, block address 



D 

Specifies direct access. 

deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for a BDAM 
data set opened for processing. The deb address operand must specify the same data 
control block as designated in the associated READ macro instruction. 

block address — RX-Type Address, (2-12), or (0) 

The block address operand specifies the address of the area containing the relative 
block address, relative track address, or actual device address of the data block being 
released. The block address operand must specify the same area as designated in the 
block address operand of the associated READ macro instruction. 



Completion Codes 



When the system returns control to the problem program, the low-order byte of register 
15 contains one of the following return codes; the three high-order bytes of register 15 
are set to zero. 

Hexadecimal 

Code Meaning 

00 Operation completed successfully. 

04 The specified data block was not in the exclusive control list. 

08 The relative track address, relative block address, or actual device address was not within 

the data set. 
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RELSE — Release an Input Buffer (QISAM and QSAM 
Input) 

The RELSE macro instruction causes immediate release of the current input buffer. The 
next GET macro instruction retrieves the first record from the next input buffer. For 
variable-length spanned records (QSAM), the input data set is spaced to the next 
segment which starts a logical record in a subsequent block. Thus, one or more blocks of 
data or records may be skipped. The RELSE macro instruction is ignored if a buffer has 
just been completed or released, if the records are unblocked, or if issued for a SYSIN 
data set. 

The RELSE macro instruction is written as follows: 



[symbol] 


RELSE 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened input data set. 
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SETL — Set Lower Limit of Sequential Retrieval 
(QISAM Input) 



The SETL macro instruction causes the control program to start processing the next 
input request at the specified record or device address. Sequential retrieval of records 
using the GET macro instruction continues from that point until the end of the data set is 
encountered or a CLOSE or ESETL macro instruction is issued. An ESETL macro 
instruction must be issued between SETL macro instructions that specify the same data 
set. 

The SETL macro instruction can specify that retrieval is to start at the beginning of the 
data set, at a specific address on the device, at a specific record, or at the first record of a 
specific class of records. For additional information on SETL functions, see OS/VS2 
MVS Data Management Services Guide. 

The SETL macro instruction is written as follows: 



[symbol] 


SETL 


deb address 

{,K[H], lower limit address } 
{ ,KC, lower limit address } 
{ ,KD[H], lower limit address } 
{ ,KCD, lower limit address } 
{ ,1, lower limit address } 
{ ,ID, lower limit address } 
{,B } 
{,BD } 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block opened for 
the indexed sequential data set being processed. 

The following operands are coded as shown, and they specify the starting point and type 
of retrieval: 



K 



Specifies that the next input operation begins at the record containing the key 
specified in the lower- limit address operand. 



KC 



H 



Specifies that the next input operation begins at the first record of the key class 
specified in the lower-limit address operand. If the first record of the specified key 
class has been deleted, retrieval begins at the next nondeleted record regardless of key 
class. 

This option, used with either K or KD, specifies that, if the key in the lower-limit 
address operand is not in the data set, retrieval begins at the next higher key. The 
character H cannot be coded with the key class operands (KC and KCD). 



KD 



Specifies that the next input operation begins at the record containing the key 
specified in the lower-limit address operand, but only the data portion of the record is 
retrieved. This operand is valid only for unblocked records. 



Macro Instruction Descriptions 151 



SETL Exit 



KCD 

Specifies that the next input operation begins at the first record of the key class 
specified in the lower-limit address operand, but only the data portion of the record is 
retrieved. This operand is valid only for unblocked records. 



I 



Specifies that the next input operation begins with the record at the actual device 
address specified in the lower-limit address operand. 



ID 

Specifies that the next input operation begins with the record at the actual device 
address specified in the lower-limit address operand, but only the data portion of the 
record is retrieved. This operand is valid only for unblocked records. 

B 

Specifies that the next input operation begins with the first record in the data set. 

BD 

Specifies that the next input operation begins with the first record in the data set, but 
only the data portion is retrieved. This operand is valid only for unblocked records. 

lower limit address — RX-Type Address, (2-12), or (0) 

The lower-limit address operand specifies the address of the area containing the key, 
key class, or actual device address that designates the starting point for the next input 
operation. If I or ID has been specified, this area must contain the actual device 
address (in the form MBBCCHHR) of a prime data record; the other types require 
that the key or key class be contained in this area. 



The error analysis (SYNAD) routine is given control if the operation could not be 
completed successfully. The exceptional condition code and general registers are set as 
shown in Appendix A. If the SETL macro instruction is not reissued, retrieval starts at 
the beginning of the data set. 
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SETPRT— Printer Setup (BSAM, QSAM, and EXCP) 

Note: to use the SETPRT macro to support the 3800 Printing Subsystem requires 
OS/VS2 MVS 3800 Printing Subsystem Selectable Unit (VS2.03.810). 

For the 3800 Printing Subsystem, the SETPRT macro instruction is used to initially set 
or dynamically change the printer control information. The following control information 
may be changed with the SETPRT macro: 

Bursting of forms (BURST parameter) 

Character arrangements to be used (CHARS parameter) 

The number of copies (COPIES parameter) 

The starting copy number (COPYNR parameter) 

Vertical formatting of a page (FCB parameter) 

Flashing of forms (FLASH parameter) 

Initializing the printer control information (INIT parameter) 

Modification of copy (MODIFY parameter) 

Blocking or unblocking of data checks (OPTCD parameter) 

For additional information on how to use the SETPRT macro instruction with the 3800, 
see IBM 3800 Printing Subsystem Programmer's Guide. 

For printers that have a universal character set (UCS) buffer or a forms control buffer 
(FCB), the SETPRT macro instruction is used to fetch UCS and FCB images from the 
image library (SYS1.IMAGELIB) and load them into their respective buffers. Note that 
FCB images for the 321 1 and 3800 are not compatible. The universal character sets for 
the 1403 and the character arrangement table modules for the 3800 are also not 
compatible. 

IBM-supplied UCS images, FCB images, and character arrangement table modules 
are included in SYS1.IMAGELIB at system generation time. For impact printers, 
user-defined character set images and forms control images can be added to 
SYS l.IMAGELIB as described in OS/ VS2 System Programming Library: Data 
Management. For the 3800, user-defined character arrangement table modules, copy 
modification modules, FCB modules, and graphic character modification modules (that 
modify the character sets) can be added to SYS l.IMAGELIB as described in IBM 
3800 Printing Subsystem Programmer's Guide. The EXLST parameter of the DCB 
macro instruction can be used to specify the address of an FCB module in storage. 

For 1403 and 3211, if the specified UCS or FCB image cannot be found in 
SYS l.IMAGELIB or the DCB exit list, the system operator is asked to specify a 
replacement name. He can therefore override an error made by the program. For 3800, 
the SETPRT routines never ask the operator to replace or respecify a parameter from the 
SETPRT macro and SETPRT processing is terminated. 

When BSAM is being used, all write operations must be checked for completion before 
the SETPRT macro instruction is issued; any incomplete write operations are purged. 
Issuing the SETPRT macro instruction for a device other than an on-line UCS printer or 
the 3800 Printing Subsystem results in an error return code. 
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The standard form of the SETPRT macro instruction is written as follows (the list and 
execute forms are shown following the standard form): 



[symbol] 


SETPRT 


dcbaddr 

[,BURS-'={N|Y}] 

[,CHARS= {name\A(address)\R(register) } 
{({name | A(address) \ R(register )},...)}] 

[,COPIES lumber] 

[,COPYNR= number] 




\ ■ 


[,FCB= {imageid \ A(address ) | R( register ) } 
{({imageid \ Maddress ) \ R( register )},{\ | A}) }] 

[,FLASH= {name } 
{([name], count)}] 

[,INIT={N|Y}] 

[,MODIFY = { {name | A( address ) | R( register ) } 
{({name \ A(address) \ R(register)},trc) }] 

[,OPTCD= {B | U } 
{(B|U},{F|U})}] 

[,REXMIT={N|Y}] 

[,UCS= {esc } 
{(esc, {F|F,V|,V})}] 



dcbaddr — A-Type Address or (2-12) 

The dcbaddr operand specifies the address of the data control block for the data set to 
be printed; the data set must be opened for output before the SETPRT macro 
instruction is issued. 

BURST={N|Y} 

The BURST operand specifies if the paper output is to be burst. BURST=Y indicates 
that the printed output is to be burst into separate sheets and stacked. BURST=N 
indicates that the printed output is to go into the continuous forms stacker. If BURST 
is not specified, the SETPRT routine assumes BURST =N. If bursting is requested, the 
printed output is threaded into the burster-trimmer-stacker. Otherwise, the printed 
output is threaded into the continuous forms stacker. The operand causes a message to 
be printed on the system console telling the operator to rethread the paper if needed. 
This operand is valid for the 3800 printer only. 

CHARS= {name \ A(address | Reregister) } 

{({name | A(address) \ R(register )},...) } 
The CHARS operand specifies one to four character arrangement tables to be used 
when printing a data set. This operand is valid for the 3800 printer only. 

name 

Name is the last four characters of the 8-byte member name for a character 
arrangement table module. For information on the modules available, see IBM 
3800 Printing Subsystem Programmer's Guide. 

A(address) 

The address subparameter specifies an in-storage address of the user-provided 
character arrangement table module. For information on the format of the 
module, see IBM 3800 Printing Subsystem Programmer's Guide. 
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SETPRT 

R( register ) 

The register subparameter specifies the register which contains an in-storage 
address of the user-provided character arrangement table module. For 
information on the format of the module, see IBM 3800 Printing Subsystem 
Programmer's Guide. 

COPlES=number 

The COPIES operand specifies the total number of copies of each page of the data set 
that is to be printed (from 1 to 255) before going to the next page. If the COPIES 
operand is omitted, one copy of each page is printed. This operand is valid for the 
3800 printer only. 

COPYNR=number 

This operand specifies the starting copy number for this transmission. Number is a 
value from 1 to 255. This operand will default to a value of 1 if not specified. This 
operand is valid for the 3800 printer only. 

FCB = { imageid | A( address ) | R( register ) } 

{({imageid | A(address ) | R( register)} A V | A}) } 
The FCB operand specifies that the forms control buffer (FCB) is to be loaded from 
the image library. When the FCB operand is specified, the OPTCD operand can also 
be specified. The possible specifications are: 

imageid 

The imageid operand specifies the forms control image to be loaded. A forms 
control image is identified by a one- to four-character name. IBM-supplied 321 1 
images are identified by imageid value of STD1 and STD2; user-designed forms 
control images are defined by the installation. For descriptions of the standard 
forms control images for the 321 1, refer to OS/VS2 System Programming 
Library: Data Management. For more information about 3800 FCB modules, see 
IBM 3800 Printing Subsystem Programmer's Guide. 

A( address ) 

The address subparameter specifies an in-storage address of the user-supplied 
forms control buffer module to be used. For information on the format of the 
module, see IBM 3800 Printing Subsystem Programmer's Guide. This 
subparameter is valid for the 3800 printer only. 

R( register ) 

The register subparameter specifies the register which contains an in-storage 
address of the user-provided forms control buffer module to be used when printing 
a data set. For information on the format of the module, see IBM 3800 Printing 
Subsystem Programmer's Guide. This subparameter is valid for the 3800 printer 
only. 

V or VERIFY 

Requests that the forms control image be displayed on the printer for visual 
verification/This operand allows forms verification and alignment using-the WTOR 
macro instruction. 

A or ALIGN 

Allows forms alignment using the WTOR macro instruction. This subparameter will 
be ignored if specified for the 3800 printer. 
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FLASH={ name } 

{([name], count)} 
The FLASH operand identifies the forms overlay frame to be used. Unless 
REXMIT=Y is coded and the forms overlay frame is still in use from the previous 
SETPRT macro issuance, a message tells the operator to insert this forms overlay 
frame into the printer. This operand also enables the specification of the number of 
copies on which the overlay is to be printed (flashed). If this operand is omitted, 
flashing ceases. This operand is valid for the 3800 printer only. 

name 

This subparameter is the one- to four-character name of the forms overlay frame. 

count 

This subparameter indicates the total number (0-255) of copies of each page of the 
data set on which the overlay will be printed, beginning with the first copy. The 
number of copies printed will not be greater than the number of copies specified by 
the COPIES operand. No copies will be flashed if the count of zero is specified. If a 
non-zero count is specified and the name of the forms overlay frame is omitted, the 
operator will not be requested to insert a frame and whichever frame is inserted will 
be used. 

INIT={N|Y} 

INIT=Y will initialize the control information in the 3800 printer with a folded 
character arrangement table, the 10-pitch Gothic character set, and a six lines per inch 
FCB corresponding to the forms size in the printer. COPIES and COPYNR will be 
initialized to 1, FLASH and MODIFY will be initialized to none, and BURST will be 
initialized to N (continuous forms). For INIT=N, all control information for the 3800 
printer will remain unchanged. Any parameters included on the same macro statement 
as the INIT operand will be processed after printer initialization has been completed. 
This operand is valid for the 3800 printer only. 

MODIFY = { name | A( address ) | R( register ) } 

{({name | A( address) \ \L(register)},trc)} 
The MODIFY operand identifies the copy modification module and an associated 
character arrangement table module to be used when modifying the data to be printed. 
This operand is valid for the 3800 printer only. 

name 

A one- to four-character name of the copy modification module stored in 
SYS1.IMAGELIB. These one to four characters are the last characters of the 
8-byte member name of a copy modification module in SYS l.IMAGELIB. 

A(address) 

The address subparameter specifies an in-storage address of the 'user-supplied copy 
modification module. For information on the format of the module, see IBM 3800 
Printing Subsystem Programmer's Guide. 

R(register) 

The register subparameter specifies a register which contains an in-storage address 
of the user 7 provided copy modification module. For information on the format of 
the module, see IBM 3800 Printing Subsystem Programmer's Guide. 

trc 

The trc subparameter specifies the table reference character used to select one of 
the character arrangement table modules to be used for the copy modification text. 
The values of 0, 1, 2, or 3 correspond to the order in which the module names have 
been specified in the CHARS operand. If trc is not included, the first character 
arrangement table module (0) is assumed. 
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SETPRT 

OPTCD={B|U } 

{({B|U},{F|UM 
The OPTCD operand specifies whether printer data checks are blocked or unblocked 
and if the printer is to operate in fold or normal mode. The possible specifications are: 



B 



Specifies that printer data checks are blocked; this option updates the DCBOPTCD 
field of the data control block. 



U 

Specifies that printer data checks are unblocked; this option updates the 
DCBOPTCD field of the data control block. 

F or FOLD 

Specifies that printing is in fold mode. This subparameter will be ignored if 
specified for the 3800 printer. 

U or UNFOLD 

Specifies that printing is in normal mode; this operand causes fold mode to revert 
to normal mode. This subparameter will be ignored if specified for the 3800 printer. 

REXMIT={N|Y} 

The specification of REXMIT=Y allows modification of the starting copy number 
(COPYNR), the number of copies of the pages in a data set to be printed (COPIES), 
the forms overlay frame to be used (FLASH), and the number of copies to be printed 
(FLASH) without changing the other control information already set up in the printer. 
The SETPRT SVC will ignore all other parameters in the parameter list. 

UCS= {esc } 

{('cjc,{F,|FV|,V})} 
The UCS operand specifies that the UCS buffer is to be loaded from the image 
library. When the UCS operand is specified, the FCB and OPTCD operands can also 
be specified. This operand will be ignored if specified for the 3800 printer. The 
possible specifications are: 

esc (character set code) 

The esc operand specifies the character set to be loaded. A character set is 
identified by a 1-4 character code. Codes for standard IBM character sets are as 
follows: 

1403 Printer: AN, HN, PC AN, PCHN, PN, QN, QNC, RN, SN, TN, XN, and YN 

3211 Printer: All, Hll, G11,P11, and Til 

For descriptions of the standard IBM character sets, refer to OS/VS2 System 
Programming Library: System Generation Reference; codes for user-designed 
character sets are defined by the installation. 

F or FOLD 

Specifies that the character set image is to be loaded in the fold mode. The fold 
mode is most often used when the EBCDIC code for lowercase alphabetic 
characters is printed as uppercase characters by a print train with lowercase type. 

V or VERIFY 

Requests that the character set image be displayed on the printer for visual 
verification. 
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Completion Codes 



After the SETPRT macro instruction is executed, a return code is placed in register 15, 
and control is returned to the instruction following the SETPRT macro instruction. Bits 
8-15 apply to the 3800 printer only. Bits 16-23 indicate the result of the attempt to load 
the printer's forms control buffer (FCB). Bits 24-31 indicate the result of the attempt to 
load a universal-character-set (UCS) buffer for printers other than the 3800. Completion 
codes 18-24 apply to all printers. Completion codes 28-44 apply only to the 3800 
printer. The codes in the following table are in hexadecimal. 



Bits 8-15 
3800 Code 

Other than Bits 16-23 
FCB FCB Code 



00 



00 



Bits 24-31 
UCS Code 

00 

04 



04 



04 



08 



Meaning 

Successful completion. 

The operator canceled the UCS load operation for one of the 
following reasons: 

• The requested chain or train was not available. 

. The UCS image could not be found in SYS1.IMAGEL1B. 

For a 321 1, the operator canceled the FCB load operation for 
one of the following reasons: 

• The form could not be aligned to match the buffer. 

• The FCB module could not be found in SYS1.IMAGELIB or 
the user's DCB exit list. 

For a 3800, the specified FCB module could not be found in 
SYS1.IMAGELIB or the DCB exit list, and SETPRT 
processing was terminated. 

The 3800 SETPRT processing was suspended for one of the 
following reasons: 

• A character arrangement table module could not be found in 
SYS1.IMAGELIB. 

• A copy modification module could not be found in 
SYS1.IMAGELIB. 

• A graphic character modification module (required by a 
character arrangement table module) could not be found in 
SYS1.IMAGELIB. 

Register contains a reason code identifying which of the 
above conditions prevailed. 

A permanent I/O error was detected when the BLDL macro 
instruction was issued to locate a UCS image in 
SYS1.IMAGELIB. 



08 



08 



0C 



0C 



A permanent I/O error was detected when the BLDL macro 
instruction was issued to locate an FCB module in 
SYS1.IMAGELIB. 

A permanent I/O error was detected when the BLDL macro 
instruction was issued to locate one of the following modules in 
SYS1.IMAGELIB: 

• A character arrangement table module 

• A copy modification module 

• A graphic character modification module. 

Register contains a reason code identifying which of the 
above conditions prevailed. 

A permanent I/O error was detected while loading the printer s 
UCS buffer. 

A permanent I/O error was detected while loading the printer's 
FCB buffer. 
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Bits 8-15 
3800 Code 
Other than 
FCB 

0C 



Bits 16-23 
FCB Code 



Bits 24-31 
UCS Code 



10 



10 



14 



14 



Bits 24-31 

General 

Code 

18 



1C 



20 

24 

Bits 24-31 
3800 Code 

28 

2C 

30 

34 
38 



SETPRT 



Meaning 

A permanenl I/O error was detected while loading one of the 
following: 

• Character arrangement tahle 

• Copy modification record 

• Starting copy number 

• Graphic character modification record 

• Forms overlay sequence control record (copy counts and 
flash counts) 

• Writable character generation module (WCGM) 

Register contains a reason code identifying which of the 
above conditions prevailed. 

A permanent I/O error was detected when an attempt was 
made to display the character set image on the printer for 
visual verification. 

A permanent I/O error was detected when an attempt was 
made to display the forms control image on the printer for 
visual verification. 

The operator canceled the UCS load because an improper 
character set image was displayed for visual verification. 

The operator canceled the FCB load because an improper 
forms control image was displayed for visual verification. 



No operation was performed for one of the following reasons: 

• The data control block was not open. 

• The data control block was not valid for a sequential data set. 

• The SETPRT parameter list was not valid. 

• The output device was not a UCS or 3800 printer. 

No operation was performed because an uncorrectable error 
occurred in a previously initiated output operation. The error 
analysis (SYNAD) routine is entered when the next PUT or 
CHECK macro instruction is issued. 

No operation was performed because an uncorrectable error 
occurred when the Block Data Check or Reset Block Data 
Check command was issued by SETPRT. 

Not enough space has been provided for the SYS1.IMAGELIB 
control blocks. 

SYS1.IMAGELIB cannot be opened to load the specified 
module. 



The operator canceled the forms overlay request. 

The operator canceled the page threading request. 

There are more writable character generation modules 
(WCGMs) requested than there are writable buffers installed 
on the printer. 

There was an invalid table reference character for copy 
modification. 

An error occurred when attempting to execute the initialize 
printer command. 
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Bits 8-15 
3800 Code 

Other than Bits 16-23 
FCB FCB Code 



Bits 24-31 

3800 Code 

3C 

40 

44 



Meaning 

Bursting was requested but the Burster-Trimmer-Stacker 
feature is not installed on the printer. 

A permanent I/O error occurred while executing a sense or 
final select character arrangement table command. 

The translate table character arrangement table entry 
references a character set which does not exist in the image 
library. 



Reason Codes — 3800 Printer Only 



These reason codes for the 3800 printer are in addition to completion codes 04-OC 
returned in register 15. The reason codes are placed in register 0. The three high-order 
bytes will be zero. The codes in the following table are in hexadecimal and indicate 
which item caused the error. 

Reason Code Meaning 

04 Character arrangement table module/record 

08 Copy modification module/record 

0C Starting copy number 

10 Graphic character modification module/record 

14 Forms overlay sequence control record 

1C ■ Writable character generation module (WCGM) 

20 Forms control buffer module 
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SETPRT — List Form 



The list form of the SETPRT macro instruction is used to construct a data management 
parameter list. 

The description of the standard form of the SETPRT macro instruction provides the 
explanation of the function of each operand. The format description below indicates the 
optional and required operands for the list form only. The dcbaddr parameter must 
appear in the list or execute form of the SETPRT macro. 

The list form of the SETPRT macro instruction is written as follows: 



[symbol] 


SETPRT 


[ dcbaddr ] 

[,BURST={N|Y}] 

[,CHARS= {[name } 
{(name,...) }] 

[,COPIES= number] 

[,COPYNR= number] 

[,FCB= {imageid } 
{(imageid, {\\ A})}] 

[,FLASH= {name } 
{([name], count)}] 

[,INIT={N|Y}] 

[,MODIFY= {name } 
{(name ,trc)}] 

[,OPTCD= {B|U } 
{({B|U},{F|U})}] 

[,REXMIT={N|Y}] 

[,UCS= {esc } 
{(C5C,{F|F,V|,V})}] 

,MF=L 



dcbaddr — A-Type Address 

BURST={N|Y} 

It is coded as shown in the standard form of the macro instruction. 

CHARS= {name } 
{(name,...)} 
It is coded as shown in the standard form of the macro instruction except for the 
A(address ) and R( register ) parameters which cannot be specified. 

COPlES=number 

It is coded as shown in the standard form of the macro instruction. 

COPYNR=number 

It is coded as shown in the standard form of the macro instruction. 

FCB= {imageid } 

{(imageid ,{V | A})} 
It is coded as shown in the standard form of the macro instruction except for the 
A(address ) and R( register ) parameters which cannot be specified. 
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FLASH= {name } 

{([name], count)} , 

It is coded as shown in the standard form of the macro instruction. 

INIT={N|Y} 

It is coded as shown in the standard form of the macro instruction. 

MODIFY = {name } 

{(name,trc) } 
It is coded as shown in the standard form of the macro instruction except for the 
ASaddress ) and R( register ) parameters which cannot be specified. 

OPTCD={B|U } 

{({B|U},{F|U})} 
It is coded as shown in the standard form of the macro instruction. 

REXMIT={N|Y} 

It is coded as shown in the standard form of the macro instruction. 

UCS= {esc } 

U«c,{F|F,V|,V})} 
It is coded as shown in the standard form of the macro instruction. 

MF=L 

The MF=L operand specifies that the list form of the macro instruction is used to 
create a parameter list that can be referenced by an execute form of the SETPRT 
macro instruction. 
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SETPRT — Execute Form 



A remote data management parameter list is referred to, and can be modified by, the 
execute form of the SETPRT macro instruction. 

The description of the standard form of the SETPRT macro instruction provides the 
explanation of the function of each operand. The format description below indicates the 
optional and required operands for the execute form only. The dcbaddr parameter must 
be specified in the list or execute form of the SETPRT macro. 

The execute form of the SETPRT macro instruction is written as follows: 



[ symbol ] 


SETPRT 


[ dcbaddr ] 

[,BURST={N|Y|*}] 

[,CHARS= {name | A( address ) | ^(register ) } 
{({name \ A(address) \ R(register)},...) } 
{* }] 

[,COPlES= {number \*}] 

UCOPYNR={number | *}] 

[,FCB = { imageid | A( address ) | R( register ) } 
{({imageid | A( address ) | R( register ),{V 1 A})} 
{* 11 

[,FLASH= {name } 
{([name], count) } 
{* }] 

[,INIT= {N|Y}] 

[,MODIFY= {name \ A( address ) \ R( register ) } 
{({name \ A(address) \ R( register)}, trc)} 
{* }] 

[,OPTCD= {B|U } 
{({B|U},{F|U})}] 

[,REXMIT={N|Y|*}] 

[,UCS= {esc } 
{<C5C,{F|F,V|,V})}] 

,MF=(E,{data management list address \ (1)}) 



dcbaddr — RX-Type Address or (2-12) 

BURST={N|Y|*} 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When BURST=* is coded, the 
BURST field in the parameter list remains as it was previously set. This operand is 
valid for the 3800 printer only. 
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CHARS = {name | A( address ) | R( register ) } 

{({name \ X(address) \ R(register)},...)} 

{* } 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When CHARS=* is coded, the 
CHARS field in the parameter list remains as it was previously set. 

COPIES- [number \*} 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When COPIES=* is coded, the 
COPIES field in the parameter list remains as it was previously set. 

COPYNR= {number | *} 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When COPYNR=* is coded, the 
COPYNR field in the parameter list remains as it was previously set. 

FCB= { {imageid \ A( address ) | R( register ) } 

{({imageid \ ^(address ) \ R(register)},{\ \ A}) } 

{* } 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When FCB=* is coded, the FCB 
field in the parameter list remains as it was previously set. 

FLASH= {name } 

{([ name ], count)} 

{* } 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When FLASH =* is coded, the 
FLASH field in the parameter list remains as it was previously set. 

INIT={N|Y} 

It is coded as shown in the standard form of the macro instruction. When INIT=Y is 
specified on the execute form of the SETPRT macro instruction, all 3800 fields in the 
parameter list (BURST, CHARS, COPIES, COPYNR, FCB, FLASH, MODIFY, and 
REXMIT) will be reset to binary zeros unless a specified field is preserved by coding 
keyword parameter=* or changed by specifying a valid subparameter for the keyword 
parameter as described in the standard form of the macro instruction. 

MODIFY= { {name | A( address ) | R( register ) } 

{({name | A( address ) | R( register )}, trc ) } 

{* } 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT=Y is specified in the 
execute form of the SETPRT macro instruction. When MODIFY=* is coded, the 
MODIFY field in the parameter list remains as it was previously set. 

OPTCD= {B | U} } 

{({B|U},{F|U})} 
It is coded as shown in the standard form of the macro instruction. 
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SETPRT 

REXMIT={N|Y|*} 

It is coded as shown in the standard form of the macro instruction except for the * 
subparameter. The * subparameter can only be used when INIT= Y is specified in the 
execute form of the SETPRT macro instruction. When REXMIT=* is coded, the 
REXMIT field in the parameter list remains as it was previously set. 

UCS= {esc } 

{(«c,{F|F,V|,V}) } 
It is coded as shown in the standard form of the macro instruction. 

MF=(E,{ data management list address | (1)}) 

This operand specifies that the execute form of the SETPRT macro instruction is 
used, and an existing data management parameter list is used. 

E — Coded as shown 

data management list address — RX-Type Address, (2-12), or (1) 
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STOW — Update Partitioned Data Set Directory (BPAM) 

The STOW macro instruction causes the system to update a partitioned data set directory 
by adding, changing, replacing, or deleting an entry in the directory. Only one entry can 
be updated at a time using the STOW macro instruction. If the entry to be added or 
replaced is a member name, the system writes an end-of-data indication following the 
member. All input/output operations using the same data control block must have 
previously been tested for completion. 

The STOW macro instruction is written as follows: 



[symbol] 


STOW 


deb address 
Jist address 
[, directory action ] 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
opened partitioned data set. The STOW macro instruction can be used only when the 
data set is opened for OUTPUT, UPDAT or OUTIN (BSAM). 

list address — RX-Type Address, (2-12), or (0) 

The list address operand specifies the address of the area containing the information 
required by the system to maintain the partitioned data set directory. The size and 
format of the area depend on the directory action requested as follows: 

Adding or Replacing a Directory Entry: The list address operand must specify an area 
at least 1 2 bytes long and beginning on a half word boundary. The following 
illustration shows the format of the area: 



List Address 



Length 
Bytes 



NAME 



TTR 



USER DATA 



10 to 62 



NAME: Specifies the member name or alias being added or replaced. The name must 
begin in the first byte of the field and be padded on the right with blanks, if necessary, 
to complete the 8-byte field. 

TT: Specifies the relative track number on which the beginning of the data set is 
located. 

R: Specifies the relative block (record) number on the track identified by TT. 

Note: The TTR field shown above must be supplied by the problem program if an 
alias (alias bit is 1) is being added or replaced. The system supplies the TTR field 
when a member name is being added or replaced. 

C: Specifies the type of entry (member or alias) for the name, the number of note list 
fields (TTRNs), and the length in half words, of the user data field. The following 
describes the meaning of the eight bits: 

Bit Meaning 

0=0 Indicates a member name. 

0=1 Indicates an alias. 

1 and 2 Indicate the number of TTRN fields (maximum of three) in the user data field. 

3-7 Indicate the total number of halfwords in the user data field. 
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STOW 

Deleting a Directory Entry: The list address operand must specify an 8-byte area that 
contains the member name or alias to be deleted. The name must begin in the first 
byte of the area and be padded on the right with blanks, if necessary, to complete the 
eight bytes. 

Changing the Name of a Member: The list address operand must specify the address 
of a 16-byte area; the first 8 bytes contain the old member name or alias, and the 
second 8 bytes contain the new member name or alias. Both names must begin in the 
first byte of their 8-byte area and be padded on the right with blanks, if necessary, to 
complete the 8-byte field. 

directory action — [A | C | D | R] 

If the directory action operand is not coded, A (add an entry) is assumed. The 
operand is coded as shown to specify the type of directory action: 

A 

Specifies that an entry is to be added to the directory. 



D 



R 



Specifies that the name of an existing member or alias is to be changed. 

Specifies that an existing directory entry is to be deleted. 

Specifies that an existing directory entry is to be replaced by a new directory entry. 
If R is coded but the old entry is not found, the new entry is added to the directory 
and a completion code of X'08' is returned in register 15. 



Completion Codes 



When the system returns control to the problem program, register 15 contains a return 
code and register contains a reason code in the low-order byte; the three high-order 
bytes of both registers are set to zero. 



Hexadecimal 




Directory Acti 


ion 




Return Code 










(Reg. 15) 


A 


R 


D 


C 


00 


The update of the 


The update of the 


The update of the 


The update of the 




directory was 


directory was 


directory was 


directory was 




completed 


completed 


completed 


completed 




successfully. 


successfully. 


successfully. 


successfully. 


04 


The directory 
already contains 
the specified 
name. 






The directory 
already contains 
the specified 
new name. 


08 


— 


The specified 


The specified 


The specified old 






name could not 


name could not 


name could not 






be found. 


be found. 


be found. 


OC 


No space left in 


No space left in 


— 


No space left in 




the directory. 


the directory. 




the directory. 




The entry could 


The entry could 




The entry could 




not be added, 


not be added, 




not be added. 




replaced, or 


replaced, or 




replaced, or 




changed. 


changed. 




changed. 
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Hexadecimal 




Directory Action 




Return Code 










(Reg. 15) 


A 


R 


D 


C 


10 


A permanent input 


A permanent input 


A permanent input 


A permanent input 




or output error 


or output error 


or output error 


or output error 




was detected. 


was detected. 


was detected. 


was detected. 




Control is not 


Control is not 


Control is not 


Control is not 




given to the 


given to the 


given to the 


given to the 




error analysis 


error analysis 


error analysis 


error analysis 




(SYNAD) routine. 


(SYNAD) routine. 


(SYNAD) routine. 


(SYNAD) routine. 


14 


The specified 


The specified 


The specified 


The specified 




data control 


data control 


data control 


data control 




block is not 


block is not 


block is not 


block is not 




open or is opened 


open or is opened 


open or is opened 


open or is opened 




for input. 


for input. 


for input. 


for input. 


18 


Insufficient 


Insufficient 


Insufficient 


Insufficient 




virtual storage 


virtual storage 


virtual storage 


virtual storage 




was available 


was available 


was available 


was available 




to perform the 


to perform the 


to perfo'rm the 


to perform the 




STOW function. 


STOW function. 


STOW function. 


STOW function. 


Hexadecimal 










Reason Code 










(Reg.0) 


Meaning 








00 


Reason code is not 


applicable. (Returned wi 


ith all return codes except 10.) 


01 


All functions; the p 


ermanent I/O error occurred while reading or wri 


iting directory 



blocks. 
02 Add and replace functions; the permanent I/O error occurred while writing an EOF mark 

after the member. 
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SYNADAF — Perform SYNAD Analysis Function 
(BDAM, BISAM, BPAM, BSAM, EXCP, QISAM, and 
QSAM) 

The SYNADAF macro instruction is used in an error analysis routine to analyze 
permanent input/output errors. The routine can be a SYNAD routine specified in a data 
control block for BDAM, BISAM, BPAM, BSAM, QISAM, QSAM, or a routine that is 
entered directly from a program that uses the EXCP macro instruction. (The EXCP 
macro instruction is described in OS/VS2 System Programming Library: Data 
Management.) 

The SYNADAF macro instruction uses register 1 to return the address of a buffer 
containing a message. The message describes the error, and can be printed by a 
subsequent PUT or WRITE macro instruction. The message consists of EBCDIC 
information and is in the form of a variable-length record. The format of the message is 
shown following the descriptions of the SYNADAF operands. 

The system does not use the save area whose address is in register 13. Instead, it provides 
a save area for its own use, and then makes this area available to the error analysis 
routine. The system returns the address of the new save area in register 1 3 and in the 
appropriate location (word 3) of the previous save area; it also stores the address of the 
previous save area in the appropriate location (word 2) of the new save area. 

The SYNADAF macro instruction passes parameters to the system in registers and 1 . 
When used in a SYNAD routine, the SYNADAF macro should be coded at the 
beginning of the routine (refer to Appendix A, Figures 4 through 6). For BISAM and 
QISAM, the SYNAD routine has to set up these parameters as explained under PARM 1 
and PARM2. To save these parameters for use by the SYNAD routine, the system stores 
them in a parameter save area that follows the message buffer as shown in the message 
buffer format. The system does not alter the return address in register 14 or the entry 
point address in register 15. 

When a SYNADAF macro instruction is used, a SYNADRLS macro instruction must be 
used to release the message buffer and save areas, and to restore the original contents of 
register 13. 
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The SYNADAF macro instruction is written as follows: 



[symbol] 


SYNADAF 


ACSMETH= {BDAM 

[,PARM1 =parm register ] 
[,PARM2 =parm register ]} 

{BPAM 

[,PARM1 =parm register ] 
[,PARM2=/?arm register ]} 






{BSAM 

[,PARM1 = parm register ] 
[,PARM2 =parm register ]} 

{QSAM 

[,PARM1 = parm register ] 
[,PARM2 =parm register ]} 

{BISAM 

[,PARM1 = dcbaddr ] 
[,PARM2= decb address ]} 

{EXCP 
[,PARM1 = iob address ]} 

{QISAM 

[,PARMl = dcbaddr ] 
[,PARM2 =parm register ]} 



ACSMETH=BDAM, BPAM, BSAM, QSAM, BISAM, EXCP, or QISAM 
The ACSMETH operand specifies the access method used to perform the 
input/output operation for which error analysis is performed. 

PARM\ =parm register, iobaddr, or dcbaddr —(2-12) or (1) 

The PARM1 operand specifies the address of information that is dependent on the 
access method being used. For BDAM, BPAM, BSAM, or QSAM, the operand 
specifies a register that contains the information that was in register 1 on entry to the 
SYNAD routine. For BISAM or QISAM, the operand specifies the address of the data 
control block; for EXCP, it specifies the address of the input/output block. If the 
operand is omitted, PARM1=(1) is assumed. 

PARM2=parm register — (2-12), (0), or RX-Type Address 

(only if ACSMETH=QISAM) 

The PARM2 operand specifies the address of additional information that is dependent 
on the access method being used. For BDAM, BPAM, BSAM, QISAM, and QSAM, 
the operand specifies a register that contains the information that was in register on 
entry to the SYNAD routine. For BISAM, the operand specifies a register that 
contains the information that was in register 1 on entry to the SYNAD routine (the 
address of the DECB). For EXCP, the operand is meaningless and should be omitted. 
If the operand is omitted, except in the case of EXCP, PARM2=(0) is assumed. 

Note: For correctly loading the registers for SYNADAF for BISAM, you may code these 
two instructions before issuing the SYNADAF macro: 



LR 



0,1 
1,8(1) 



GET DECB ADDRESS 
GET DCB ADDRESS 
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SYNADAF 



Completion Codes 



When the system returns control to the problem program, the low-order byte of register 
contains one of the following return codes; the three high-order bytes of register are 
set to zero. 

Hexadecimal 

Code Meaning 

00 Successful completion. Bytes 8-13 of the message buffer contain blanks. 

04 Successful completion. Bytes 8-13 of the message buffer contain binary data. 

08 Unsuccessful completion. The message can be printed, but some information is missing in 

bytes 50-127 and is represented by asterisks. If byte 8 is a blank (X'40'), then bytes 9-13 
are either blanks or are uninitialized. If byte 8 is not a blank, then data was read and bytes 
8-13 of the message buffer contain binary data. 



Message Buffer Format 



The following illustration shows the format of the message buffer; the address of the 
buffer is returned in register 1 . 



Message Buffer 
Byte 4 



LLbb 



I I b b 



Doubleword 
Boundary 

LL= 128; 11= 124: bb=000 v - 

50 



8 


12 


14 


Input : 


Input 

Buffer 

Address 


No. of 

Bytes 

Read 




8 


14 


Output ■• 


(Blanks) 





Jobname 



84 



Operation 
Attempted 



59 



91 



Stepname 



68 



Unit 
Address 



(Blanks) 



Device 
Type 



75 



Error Description 



107 



1r 



DDname 



84 



50 



Unit Record: 



Magnetic Tape: 



Direct Access: 



Parameter Save Area 
128 



Parameter 
Register 
(PARM2) 



132 



Parameter 
Register l 
(PARMl) 



136 





107 












122 


1 28 




(Asterisks) 


' 


Access 
Method 




I07 


II5 


1 20 


128 




Relative Block 
Number (decimal) 




Access 
Method 


(Blanks) 




107 


I 22 


128 




Actual Track Address and Block Number 
(BBCC'HHR in hexadecimal format) 


- 


Access 
Method 





(End of Buffer - 
-Beginning of 
Parameter Save Area ) 
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Notes: 

• The device type field (bytes 72-73) contains UR for a unit record device, TA for a 
magnetic tape device, or DA for a direct-access device. 

• If a message field (bytes 91-105) is not applicable to the type of error that occurred, it 
contains N/A or NOT APPLICABLE. 

• If no data was transmitted, or if the access method is QISAM, bytes 8-13 contain 
blanks or binary zeros. 

• If the access method is BISAM, bytes 68-70, 84-89, and 107-120 contain asterisks. 

» If the access method is BDAM, and if the error was an invalid request, bytes 107-120 
contain EBCDIC zeros. 

I • The unit address field (bytes 68-70) contains the letters 'JES' if the data set is SYSIN 
or SYSOUT. 
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SYNADRLS— Release SYNADAF Buffer and Save 
Areas (BDAM, BISAM, BPAM, BSAM, EXCP, 
QISAM, and QSAM) 

The SYNADRLS macro instruction releases the message buffer, parameter save area, 
and register save area provided by a SYNADAF macro instruction. It must be used to 
perform this function whenever a SYNADAF macro instruction is used. 

When the SYNADRLS macro instruction is issued, register 13 must contain the address 
of the register save area provided by the SYNADAF macro instruction. The control 
program loads register 13 with the address of the previous save area, and sets word 3 of 
that save area to zero. Thus, when control is returned, the save area pointers are the 
same as before the SYNADAF macro instruction was issued. 

The SYNADRLS macro instruction is written as follows: 



[ symbol ] 


SYNADRLS 


b 



When the system returns control to the problem program, the low-order byte of register 
contains one of the following return codes; the three high-order bytes of register are 
set to zero. 

Hexadecimal 

Code Meaning 

00 Successful completion. 

08 Unsuccessful completion. The buffer and save areas were not released; the contents of 

register 13 remain unchanged. Register 13 does not point to the save area provided by the 
SYNADAF macro instruction, or this save area is not properly chained to the previous 
save area. 
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TRUNC — Truncate an Output Buffer (QSAM 
Output — Fixed- or Variable-Length Blocked Records) 

The TRUNC macro instruction causes the current output buffer to be regarded as full. 
The next PUT or PUTX macro instruction specifying the same data control block uses 
the next buffer to hold the logical record. 

When a variable-length spanned record is being truncated and logical record interface is 
specified (that is, if BFTEK=A is specified in the DCB macro instruction, or if a 
BUILDRCD macro instruction is issued), the system segments and writes the record 
before truncating the buffer. Therefore, the block being truncated is the one that 
contains the last segment of the spanned record. 

The TRUNC macro instruction is ignored if it is used for unblocked records; if it is used 
when a buffer is full, or if it is used without an intervening PUT or PUTX macro 
instruction. 

The TRUNC macro instruction is written as follows: 



[symbol] 


TRUNC 


deb address 



deb address — RX-Type Address, (2-12), or (1) 

The deb address operand specifies the address of the data control block for the 
sequential data set opened for output. The record format in the data control block 
must not indicate standard blocked records (RECFM=FBS). 



174 OS/VS2 Data Management Macro Instructions 



WAIT — Wait for One or More Events (BDAM, BISAM, 
BPAM, and BSAM) 

The WAIT macro instruction is used to inform the control program that performance of 
the active task cannot continue until one or more specific events, each represented by a 
different ECB (event control block), have occurred. In the context of this manual, the 
ECBs represent completion of I/O processing associated with a READ or WRITE 
macro. ECBs are located at the beginning of access method DECBs (data event control 
blocks), so that the DECB name provided in READ and WRITE macros is also used for 
WAIT. A description of the ECB is found in "Appendix A" and in OS/VS2 System 
Programming Library: Debugging Handbook. For information on when to use the 
WAIT macro, see OS/VS2 MVS Data Management Services Guide. 

The control program takes the following action: 

• For each event that has already occurred (each ECB is already posted), the count of 
the number of events is decreased by 1. 

• If the number of events is by the time the last event control block is checked, 
control is returned to the instruction following the WAIT macro instruction. 

• If the number of events is not by the time the last ECB is checked, control is not 
returned to the issuing program until sufficient ECBs are posted to bring the number 
to 0. Control is then returned to the instruction following the WAIT macro 
instruction. 

• The events will be posted complete by the system when all I/O has been completed, 
temporary errors have been corrected, and length checking has been performed. The 
DECB is not checked for errors or exceptional conditions, nor are end-of-volume 
procedures initiated. Your program must perform these operations. 

The WAIT macro instruction is written as follows: 



[ symbol ] 


WAIT 


[ number of events ] 

{,ECB= addr | ECBLIST= a^/r } 

[,LONG={YES|NO}] 



number of events 

Specifies a decimal integer from to 255. Zero is an effective NOP instruction; one is 
assumed if the operand is omitted. The number of events must not exceed the 
number of event control blocks. 

ECB=addr 

Specifies the address of the event control block (or DECB) representing the single 
event that must occur before processing can continue. The operand is valid only if the 
number of events is specified as one or is omitted. 

ECBUST=addr 

Specifies the address of a virtual storage area containing one or more consecutive 
fullwords on a fullword boundary. Each fullword contains the address of an event 
control block (or DECB); the high-order bit in the last word (address) must be set to 
1 to indicate the end of the list. The number of event control blocks must be equal to 
or greater than the specified number of events. 

LONG={YES|NO} 

Specifies whether the task is entering a long wait or a regular wait. Normally I/O 
events should not be considered "long" unless it is anticipated that operator 
intervention will be required. 
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Caution: A job step with all of its tasks in a WAIT condition is terminated upon 
expiration of the time limits that apply to it. 

Access method ECBs are maintained entirely by the access methods and supporting 
control program facilities. The user may inspect access method ECBs, but should never 
modify them. 
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WRITE— Write a Block (BDAM) 



The WRITE macro instruction causes the system to add or replace a block in an existing 
direct data set. (This version of the WRITE macro instruction cannot be used to create a 
direct data set because no capacity record facilities are provided.) Control may be 
returned before the block is written. The output operation must be tested for completion 
using a CHECK or WAIT macro instruction. A data event control block, shown in 
Appendix A is constructed as part of the macro expansion. 

The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 



[ symbol ] 


WRITE 


decb name 

>type 

ydcb address 

,{area address | 'S'} 

,{ length |'S'} 

,{key address | 'S' | 0} 

, block address 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 

type — {DA[F] } 

{DI[F | X] } 

(DK[F|X]} 

The type operand is coded in one of the combinations shown to specify the type of 
write operation and optional services performed by the system: 



DA 



DI 



Specifies that a new data block is to be added to the data set in the first available 
space; the search for available space starts at the device address indicated in the 
area specified in the block address operand. Fixed-length records are added to a 
data set by replacing dummy records. Variable-length records are added to a data 
set by using available space on a track. For more information on adding records to 
a direct data set, see OS/VS2 MVS Data Management Services Guide. The 
description of the DCB macro instruction, LIMCT operand, contains a description 
of the search. 

[ 

Specifies that a data block and key, if any, are to be written at the device address 
indicated in the area specified in the block address operand. Any attempt to write 
a capacity record (R0) is an invalid request when relative track addressing or actual 
device addressing are used, but when relative block addressing is used, relative 
block is the first data block in the data set. 



DK 



Specifies that a data block (only) is to be written using the key in the area specified 
by the key address operand as a search argument; the search for the block starts at 
the device address indicated in the area specified in the block address operand. 
The description of the DCB macro instruction, LIMCT operand, contains a 
description of the search. 
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F 

Requests that the system provide block position feedback into the area specified in 
the block address operand. This character can be coded as a suffix to DA, DI, or 
DK as shown above. 

X 

Requests that the system release the exclusive control requested by a previous 
READ macro instruction and provide block position feedback into the area 
specified in the block address operand. This character can be coded as a suffix to 
DI or DK as shown above. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened BDAM data set. 

area address — A-Type Address, (2-12), or 'S' 

The area address operand specifies the address of the area that contains the data 
block to be written. 'S' can be coded instead of an area address only if the data block 
(or key and data) are contained in a buffer provided by dynamic buffering; that is, 'S' 
was coded in the area address operand of the associated READ macro instruction. If 
'S' is coded in the WRITE macro instruction, the area address from the READ macro 
instruction data event control block must be moved into the WRITE macro instruction 
data event control block; the buffer area acquired by dynamic buffering is released 
after the WRITE macro instruction is executed. See Appendix A for a description of 
the data event control block. 

length — symbol, decimal digit, absexp, (2-12) or 'S' 

The length operand specifies the number of data bytes to be written up to a maximum 
of 32,760. If 'S' is coded, it specifies that the system uses the value in the block size 
(DCBBLKSI) field as the length. When undefined-length records are used, if the 
WRITE macro instruction is for update and the length specified differs from the 
original block, the new block will be truncated or padded with binary zeros 
accordingly. The problem program can check for this situation in the SYNAD routine. 

If the length operand is omitted for format-U records, no error indication is given 
when the program is assembled, but the problem program must insert a length into the 
data event control block before the WRITE macro instruction is executed. 

key address — A-Type Address, (2-12), 'S', or 

The key address operand specifies the address of the area that contains the key to be 
used. 'S' is specified instead of an address only if the key is-contained in an area 
acquired by dynamic buffering. If the key is not written or used as a search argument, 
zero is specified instead of a key address. 

block address — A-Type Address or (2-12) 

The block address operand specifies the address of the area that contains the relative 
block address, relative track address, or actual device address used in the output 
operation. The length of the area depends on the type of addressing used and if the 
feedback option (OPTCD=F) is specified in the data control block. 

If OPTCD=F has been specified in the DCB macro and F or X is specified in the 
WRITE macro, then you must provide a relative block address in the form specified 
by OPTCD in the DCB macro. For example, if OPTCD=R is specified, you must 
provide a 3-byte relative block address; if OPTCD=A is specified, you must provide 
an 8-byte actual device address (MBBCCHHR); if neither is specified, you must 
provide a 3-byte relative block address (TTR). 

If OPTCD=F has not been specified in the DCB macro and F or X is specified in the 
WRITE macro, then you must provide an 8-byte actual device address 
(MBBCCHHR) even if relative block or relative track addressing is being used. 
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WRITE — Write a Logical Record or Block of Records 
(BISAM) 

The WRITE macro instruction causes the system to add or replace a record or replace an 
updated block in an existing indexed sequential data set. Control may be returned to the 
problem program before the block or record is written. The output operation must be 
tested for completion using a WAIT or CHECK macro instruction. A data event control 
block, shown in Appendix A, is constructed as part of the macro expansion. 

The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 



[symbol] 


WRITE 


decb name 

>type 

,dcb address 
,{area address | 'S'} 
Alength |'S'} 
,key address 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 

type — {K | KN} 

The type operand is coded as shown to specify the type of write operation: 



K 



Specifies that either an updated unblocked record or a block containing an updated 
record is to be written. If the record has been read using a READ KU macro 
instruction, the data event control block for the READ macro instruction must be 
used as the data event control block for the WRITE macro instruction, using the 
execute form of the WRITE macro instruction. 

KN 

Specifies that a new record is to be written, or a variable-length record is to be 
rewritten with a different length. All records or blocks of records read using READ 
KU macro instructions for the same data control block must be written back before 
a new record can be added except when the READ KU and WRITE KN refer to 
the same DECB. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened existing indexed sequential data set. If a block is written, the data control 
block address must be the same as the deb address operand in the corresponding 
READ macro instruction. 

area address — A-Type Address, (2-12), or 'S' 

The area address operand specifies the address of the area containing the logical 
record or block of records to be written. The first sixteen bytes of this area are used 
by the system and should not contain your data. The area address must specify a 
different area than the key address. When new records are written (or when 
variable-length records are rewritten with a different length), the area address of the 
new record must always be supplied by the problem program. This area may be 
altered by the system. *S' may be coded instead of an address only if the block of 
records is contained in an area provided by dynamic buffering; that is, 4 S' was coded 
for the area address operand in the associated READ KU macro instruction. This 
area is released after execution of a WRITE macro instruction using the same DECB. 
The area can also be released by a FREEDBUF macro instruction. 
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The following illustration shows the format of the area: 



Area — 
Address 



Control 
Program Use 



Logical Record (WRITE KN) or Block of Records (WRITE K) 



Indexed sequential buffer and work area requirements are discussed in OS/VS2 
MVS Data Management Services Guide. 

length — symbol, decimal digit, absexp, (2-12) or *S' 

The length operand specifies the number of data bytes to be written, up to a 
maximum of 32,760. Specify 'S' unless a variable-length record will be rewritten with 
a different length. 

key address — A-Type Address or (2-12) 

The key address operand specifies the address of the area containing the key of the 
new or updated record. The key address must specify a different area than the area 
address. For blocked records, this is not necessarily the high key in the block. For 
unblocked records, this field should not overlap with the work area specified in the 
MSWA parameter of the DCB macro instruction. 

Note: When new records are written, the key area may be altered by the system. 
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WRITE— Write a Block (BPAM and BSAM) 



The WRITE macro instruction causes the system to add or replace a block in a sequential 
or partitioned data set being created or updated. Control may be returned to the problem 
program before the block is written. The output operation must be tested for completion 
using the CHECK macro instruction. A data event control block, shown in Appendix A, 
is constructed as part of the macro expansion. 

If translation from EBCDIC code to ASCII code is requested, issuing multiple WRITE 
macro instructions for the same record causes an error because the first WRITE macro 
instruction issued causes the output data in the output buffer to be translated into ASCII 
code. 

If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro 
instructions must refer to the same data event control block. Refer to the list form of the 
READ or WRITE macro instruction for a description of how to construct a data event 
control block; refer to the execute form of the READ or WRITE macro instruction for a 
description of modifying an existing data event control block. 

The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 



[symbol] 


WRITE 


decb name 
,SF 

ydcb address 
,area address 
[, length |,'S'] 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 

SF 

Specifies normal, sequential, forward operation. 

deb address — A-Type Address, or (2-12) 

The deb address operand specifies the address of the data control block for the 
opened data set being created or processed. If the data set is being updated, the data 
control block address must be the same as the deb address operand in the 
corresponding READ macro instruction. 

area address — A-Type Address or (2-12) 

The area address operand specifies the address of the area that contains the data 
block to be written; if a key is written, the key must precede the data in the same area. 

length — symbol, decimal digit, absexp, (2-12) or 'S' 

The length operand specifies the number of bytes to be written; this operand is 
specified for only undefined-length records (RECFM=U) or ASCII records 
(RECFM=D) when the DCB BUFOFF operand is zero. If the data is to be translated 
from EBCDIC code to ASCII code, the maximum length is 2,048; otherwise, the 
maximum length is 32,760 bytes. 'S' can be coded to indicate that the value specified 
in the block size (DCBBLKSI) field of the data control block is used as the length to 
be written. The length operand should be omitted for all record formats except 
format-U and format-D (when BUFOFF=0). 

If the length operand is omitted for format-U or format-D (with BUFOFF=0) 
records, no error indication is given when the program is assembled, but the problem 
program must insert a length into the data event control block before the WRITE 
macro is issued. 
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WRITE — Write a Block (Create a BDAM Data Set with BSAM) 

The WRITE macro instruction causes the system to add a block to the direct data set 
being created. For fixed-length blocks, the system writes the capacity record 
automatically when the current track is filled; for variable and undefined-length blocks, a 
WRITE macro instruction must be issued for the capacity record. Control may be 
returned before the block is written. The output operations must be tested for completion 
using a CHECK macro instruction. A data event control block, shown in Appendix A, is 
constructed as part of the macro expansion. 

The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form) : 



[symbol] 


WRITE 


decb name 

.type 

,dcb address 

,area address 

I length |,'S'] 

[,next address] 



decb name — symbol 

The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 

type — {SF | SFR | SD | SZ} 

The type operand is coded as shown, to specify the type of write operation performed 
by the system: 



SF 



Specifies that a new data block is to be written in the data set. 



SFR 



Specifies that a new variable-length spanned record is to be written in the data set, 
and next address feedback is requested. This operand can be specified only for 
variable-length spanned records (BFTEK=R and RECFM=VS are specified in the 

I data set control block). If type SFR is specified, the next address operand must be 

| included. 

SD 

Specifies that a dummy data block is to be written in the data set; dummy data 
blocks can be written only when fixed-length records with keys are used. 

SZ 

Specifies that a capacity record (RO) is to be written in the data set; capacity 

records can be written only when variable-length or undefined-length records are 
used. 

deb address — A-Type Address or (2-12) 

The deb address operand specifies the address of the data control block opened for 
the data set being created. DSORG=PS (or PSU) and MACRF=WL must be 
specified in the DCB macro instruction to create a BDAM data set. 

area address — A-Type Address or (2-12) 

The area address operand specifies the address of the area that contains the data 
block to be added to the data set. If keys are used, the key must precede the data in 
the same area. For writing capacity records (SZ), the area address is ignored and can 
be omitted (the system supplies the information for the capacity record). For writing 
dummy data blocks (SD), the area need be only large enough to hold the key plus one 
data byte. The system constructs a dummy key with the first byte set to all one bits 
(hexadecimal FF) and adds the block number in the first byte following the key. 
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WRITE— BSAM 

When a dummy block is written, a complete block is written from the area 
immediately following the area address; therefore, the area address plus the value 
specified in the BLKSIZE and KEYLEN operands must be within the area allocated 
to the program writing the dummy blocks. 

length — symbol, decimal digit, absexp, (2-12), or 'S' 

The length operand is used only when undefined-length (RECFM=U) blocks are 
being written. The operand specifies the length of the block, in bytes, up to a 
maximum of 32,760. If 'S' is coded, it specifies that the system is to use the length in 
the block size (DCBBLKSI) field of the data control block as the length of the block 
to be written. 

If the length operand is omitted for format-U records, no error indication is given 
when the program is assembled, but the problem program must insert a length into the 
data event control block before the WRITE is issued. 

next address — A-Type Address or (2-12) 

The next address operand specifies the address of the area where the system places 
the relative track address of the next record to be written. Next address feedback can 
be requested only when variable-length spanned records are used. 

Note: When variable-length spanned records are used (RECFM=VS and BFTEK=R are 
specified in the data control block), the system writes capacity records (R0) 
automatically in the following cases: 

• When a record spans a track. 

• When the record cannot be written completely on the current volume. In this case, all 
capacity records of remaining tracks on the current volume are written; tracks not 
written for this reason are still counted in the search limit specified in the LIMCT 
operand of the data control block. 

• When the record written is the last record on the track, the remaining space on the 
track cannot hold more than eight bytes of data. 
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Completion Codes 



After the write has been scheduled and control has been returned to the user's program, 
the three high-order bytes of register 15 are set to zero; the low-order byte contains one 
of the following return codes: 



Variable or Undefined-Length 

(SF or SFR) (SZ) 



Return 




Code 


Meaning 




Fixed-Length 




(SForSD) 


00 


Block will be written. 




(If the previous return 




code was 08, a block 




is written only if the 




DD statement specifies 




secondary space 




allocation and 




sufficient space is 




available. 



04 



08 



0C 



Block will be written, 
followed by a capacity 
record. 



Block will be written, 
followed by capacity 
record. The next block 
requires secondary 
space allocation. 



Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 



Block will be written. 
(If the previous return 
code was 08, a block 
is written only if the 
DD statement specifies 
secondary space 
allocation and 
sufficient space is 
available. 

Block was not written; 
write a capacity record 
(SZ) to describe the 
current track, then 
reissue. 



Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 



Capacity record was 
written; another track 
is available. 



Capacity record was 
written. The next 
block requires secondary 
space allocation. This 
code is not issued if 
the WRITE SZ is the 
only WRITE macro 
instruction issued on 
a one-track secondary 
extent. 

Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 



184 OS/VS2 Data Management Macro Instructions 



WRITE— List Form 



The list form of the WRITE macro instruction is used to construct a data management 
parameter list in the form of a data event control block (DECB). Refer to Appendix A 
for a description of the various fields in the DECB for each access method. 

The description of the standard form of the WRITE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method as well as the meaning of 'S' when 
coded for the area address, length, and key address operands. For each access method, 
'S' can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the list form only, but does not indicate optional and required 
operands for any specific access method. 

The list form of the WRITE macro instruction is written as follows: 



[symbol] 


WRITE 


decb name 

. type 

,[dcb address] 

,[area address | 'S'] 

,[ length \*S'] 

,[key address | 'S' | next address ] 

,[ block address] 

,MF=L 



decb name — symbol 

type — Code one of the types shown in the standard form 

deb address — A-Type Address 

area address — A-Type Address or 'S' 

length — symbol, decimal digit, absexp, or 'S' 

key address — A-Type Address or *S' 

next address — A-Type Address 

block address — A-Type Address 

MF=L — Coded as shown 

The MF=L operand specifies that the WRITE macro instruction is used to create a 
data event control block that will be referenced by an execute-form instruction. 
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WRITE — Execute Form 



A remote data management parameter list (data event control block) is used in, and can 
be modified by, the execute form of the WRITE macro instruction. The data event 
control block can be generated by the list form of either a READ or WRITE macro 
instruction. 

The description of the standard form of the WRITE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of *S' when 
coded for the area address, length, and key address operands. For each access method, 
'S' can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the execute form only, but does not indicate the optional and 
required operands for any specific access method. 

The execute form of the WRITE macro instruction is written as follows: 



[symbol] 


WRITE 


decb address 

,type 

\dcb address] 

,[area address | 'S'] 

,[!ength\'S>] 

,[key address | 'S' | next address] 

,[ block address] 

,MF=E 



decb address — RX-Type Address or (2-12) 

type — Code one of the types shown in the standard form 

deb address — RX-Type Address or (2-12) 

area address — RX-Type Address, (2-12), or 'S' 

length — symbol, decimal digit, absexp, (2-12), or 'S' 

key address — RX-Type Address, (2-12), or 'S' 

next address — RX-Type Address or (2-12) 

block address — RX-Type Address or (2-12) 

MF=E — Coded as shown 

The MF=E operand specifies that the execute form of the WRITE macro instruction 
is used, and an existing data event control block (specified in the decb address 
operand) is to be used by the access - method. 
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XLATE — Translate to and from ASCII (BSAM and 
QSAM) 

The XLATE macro instruction is used to translate the data in an area in virtual storage 
from ASCII code to EBCDIC code or from EBCDIC code to ASCII code. 

To determine the ASCII to EBCDIC or EBCDIC to ASCII translation codes, see 
System/ 370 Reference Summary, GX20-1850. When translating EBCDIC code to 
ASCII code, all ASCII code not having an EBCDIC equivalent is translated to X'3F'. 
When translating ASCII code to EBCDIC code, all EBCDIC code not having an ASCII 
equivalent is translated to X'lA'. Since ASCII uses only 7 bits in each byte, bit is 
always set to zero during EBCDIC to ASCII translation and is expected to be zero 
during ASCII to EBCDIC translation. 

The XLATE macro instruction is written as follows: 



[symbol] 


XLATE 


area address 
, length 
[,TO={A|EJ] 



area address — RX-Type Address, symbol, decimal digit, absexp, (2-12), or (1) 
The area address operand specifies the address of the area that is to be translated. 

length — symbol, decimal digit, absexp, (2-12), or (0) 

The length operand specifies the number of bytes to be translated. 

TO={A|E} 

The TO operand specifies the type of translation that is requested. If this operand is 
omitted, E is assumed. The following describes the characters that can be specified: 



E 



Specifies that translation from EBCDIC code to ASCII code is requested. 



Specifies that translation from ASCII code to EBCDIC code is requested. 
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APPENDIX A: STATUS INFORMATION 
FOLLOWING AN INPUT/OUTPUT OPERATION 



Following an input/output operation, the control program makes certain status 
information available to the problem program. This information is a 2-byte exception 
code, or a 16-byte field of standard status indicators, or both. 

Exception codes are provided in the data control block (QISAM), or in the data event 
control block (BISAM and BDAM). The data event control block is described below, 
and the exception code lies within the block as shown in the illustration for the data 
event control block. If a DCBD macro instruction is coded, the exception code in a data 
control block can be addressed as two 1-byte fields, DCBEXCD1 and DCBEXCD2. The 
exception codes can be interpreted by referring to Figures 1-3. 

Status indicators are available only to the error analysis routine designated by the 
SYNAD entry in the data control block. A pointer to the status indicators is provided 
either in the data event control block (BSAM, BPAM, and BDAM), or in register 
(QISAM and QSAM). The contents of registers on entry to the SYNAD routine are 
shown in Figures 4-6; the status indicators are shown in Figure 7. 

Data Event Control Block 

A data event control block is constructed as part of the expansion of READ and WRITE 
macro instructions and is used to pass parameters to the control program, help control 
the read or write operation, and receive indications of the success or failure of the 
operation. The data event control block is named by the READ or WRITE macro 
instruction, begins on a fullword boundary, and contains the information shown in the 
following illustration: 







Field Contents 




Offset From DECB 








Address (Bytes) 


BSAM and BPAM 


BISAM 


BDAM 





ECB 


ECB 


ECB' 


+4 


Type 


Type 


Type 


+6 


Length 


Length 


Length 


+8 


DCB address 


DCB address 


DCB address 


+ 12 


Area address 


Area address 


Area address 


+ !6 


IOB address 


Logical record 
address 


IOB address 


+20 




Key address 


Key address 


+24 




Exception code 
(2 bytes) 


Block address 


+28 






Next address 



Exception codes are returned in bytes +1 and +2 of the ECB by the control program. 

The event control block (ECB) is used by the control program to test for completion of 
the read or write operation. The ECB is located in the first word of the DECB. 

The type, length, data control block address, area address, key address, block address, 
and next address information is taken from the operands of the macro instruction and 
placed in the DECB for use by the control program. For BISAM, exception codes are 
returned by the control program after the corresponding WAIT or CHECK macro 
instruction is issued, as indicated in Figure 1. For BDAM, BSAM, BPAM, and QSAM, 
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the control program provides a pointer to the IOB containing the status indicators shown 
in Figure 7. 



Exception 








Code Bit 








in DECB 


READ 


WRITE 


Condition if On 





X 


Type K 


Record not found 


1 


X 


X 


Record length check 


2 




Type KN 


Space not found 


3 


X 


Type K 


Invalid request 


4 


X 


X 


Uncorrectable I/O 
error 


5 


X 


X 


Unreachable block 


6 


X 




Overflow record 1 


7 




Type KN 


Duplicate record 


8-15 




8-15 


Reserved for 



control program use 

'The SYNAD routine is entered only if the CHECK macro is issued after the READ macro, and 
bit 0, 4, 5, or 7 is also on. 

Figure 1. Exception Code Bits — BISAM 

Notes for Figure 1: 

Record Not Found: This condition is reported if the logical record with the specified key 
is not found in the data set, if the specified key is higher than the highest key in the 
highest level index, or if the record is not in either the prime area or the overflow area of 
the data set. 

Record Length Check: This condition is reported, for READ and update WRITE macro 
instructions, if an overriding length is specified and (1) the record format is blocked, (2) 
the record format is unblocked but the overriding length is, greater than the length known 
to the control program, or (3) the record is fixed length and the overriding length does 
not agree with the length known to the control program. This condition is reported for 
the add WRITE macro instruction if an overriding length is specified. 

When blocked records are being updated, the control program must find the high key in 
the block in order to write the block. (The high key is not necessarily the same as the key 
supplied by the problem program.) The high key is needed for writing because the 
control unit for direct-access devices permits writing only if a search on equal is satisfied; 
this search can be satisfied only with the high key in the block. If the user were permitted 
to specify an overriding length shorter than the block length, the high key might not be 
read; then, a subsequent write request could not be satisfied. In addition, failure to write 
a high key during update would make a subsequent update impossible. 

Space Not Found in Which to Add a Record: This condition is reported if no room exists 
in either the appropriate cylinder overflow area or the independent overflow area when a 
new record is to be added to the data set. The data set is not changed in any way in this 
situation. 

Invalid Request: This condition is reported for either of two reasons. First, if byte 25 of 
the data event control block indicates that this request is an update WRITE macro 
instruction corresponding to a READ (for update) macro instruction, but the 
input/output block (IOB) for the READ is not found in the update queue. This 
condition could be caused by the problem program altering the contents of byte 25 of the 
data event control block. Second, if a READ or WRITE macro instruction specifies 
dynamic buffering (that is, 'S' in the area address operand) but the DCBMACRF field 
of the data control block does not specify dynamic buffering. 
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Uncorrectable Input/Output Error: This condition is reported if the control program's 
error recovery procedures encounter an uncorrectable error in transferring data. 

Unreachable Block: This condition is reported if an uncorrectable input/output error 
occurs while searching the indexes or following an overflow chain. It is also posted if the 
data field of an index record contains an improper address (that is, points to the wrong 
cylinder or track or is an invalid address). 

Overflow Record: This condition is reported if the record just read is an overflow record. 
(See the section on direct retrieval and update of an indexed sequential data set in 
OS/VS2 MVS Data Management Services Guide for consideration during BIS AM 
updating.) 

Duplicate Record Presented for Inclusion in the Data Set: This condition is reported if the 
new record to be added has the same key as a record in the data set. However, if the 
delete option was specified and the record in the data set is marked for deletion, this 
condition is not reported. Instead the new record replaces the existing record. 

If the record format is blocked and the relative key position is zero, the new record 
cannot replace an existing record that is of equal key and is marked for deletion. 



Exception Code 




Code Set by 










Field 


Bit 


CLOSE GET 


PUT 


PUTX 


SETL 


Condition if On 


DCBEXCDI 











TypeK 


Record Not Found 



Type I 



DCBEXCD2 



3 








4 




X 




5 


X 




X 


6 




X 




7 


X 


X 





1 






X 
X 


2 


X 






3 




X 




4 






X 


5-7 









Invalid actual address for lower 
limit 

Space not found in which to add 
a record 

Invalid request 

Uncorrectable input error 

Uncorrectable output error 

Block could not be reached 
(input) 

Block could not be reached 
(update) 

Sequence check 

Duplicate record 

Data control block closed when 
error routine entered 

Overflow record 1 

Incorrect record length 

Reserved for future use 



!The SYNAD routine is entered only if bit 4, 5, 6, or 7 of DCBEXCDI is also on. 

Figure 2. Exception Code Bits — QISAM 



Notes for Figure 2: 

Record Not Found: This condition is reported if the logical record with the specified key 
is not found in the data set, if the specified key is higher than the highest key in the 
highest level index, or if the record is not in either the prime area or the overflow area of 
the data set. 

Invalid Actual Address for Lower Limit: This condition is reported if the specified lower 
limit address is outside the space allocated to the data set. 
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Space Not Found in Which to Add a Record: This condition is reported if the space 
allocated to the data set is already filled. In the locate mode, a buffer segment address is 
not provided. In the move mode, data is not moved. 

Invalid Request: This condition is reported if (1) the data set is already being referred to 
sequentially by the problem program, (2) the buffer cannot contain the key and the data, 
or (3) the specified type is not also specified in the DCBMACRF field of the data 
control block. 

Uncorrectable Input Error: This condition is reported if the control program's error 
recovery procedures encounter an uncorrectable error when transferring a The block 
from secondary storage to an input buffer. The buffer address is placed in register 1 , and 
the SYNAD routine is given control when a GET macro instruction is issued for the first 
logical record. 

Uncorrectable Output Error: This condition is reported if the control program's error 
recovery procedures encounter an uncorrectable error when transferring a block from an 
output buffer to secondary storage. If the error is encountered during closing of the data 
control block, bit 2 of DCBEXCD2 is set to 1 and the SYNAD routine is given control 
immediately. Otherwise, control program action depends on whether load mode or scan 
mode is being used. 

If a data set is being created (load mode), the SYNAD routine is given control when the 
next PUT or CLOSE macro instruction is issued. In the case of a failure to write a data 
block, register 1 contains the address of the output buffer, and register contains the 
address of a work area containing the first 16 bytes of the IOB; for other errors, the 
contents of register 1 are meaningless. After appropriate analysis, the SYNAD routine 
should close the data set or end the job step. If records are to be subsequently added to 
the data set using the queued indexed sequential access method (QISAM), the job step 
should be terminated by issuing an ABEND macro instruction. (ABEND closes all open 
data sets. However, an ISAM data set is only partially closed, and it can be reopened in a 
later job to add additional records by using QISAM). Subsequent execution of a PUT 
macro instruction would cause reentry to the SYNAD routine, since an attempt to 
continue loading the data set would produce unpredictable results. 

If a data set is being processed (scan mode), the address of the output buffer in error is 
placed in register 1, the address of a work area containing the first 16 bytes of the IOB is 
placed in register 0, and the SYNAD routine is given control when the next GET macro 
instruction is issued. Buffer scheduling is suspended until the next GET macro instruction 
is reissued. 

Block Could Not be Reached (Input): This condition is reported if the control program's 
error recovery procedures encounter an uncorrectable error in searching an index or 
overflow chain. The SYNAD routine is given control when a GET macro instruction is 
issued for the first logical record of the unreachable block. 

Block Could Not be Reached (Output): This condition is reported if the control program's 
error recovery procedures encounter an uncorrectable error in searching an index or 
overflow chain. 

If the error is encountered during closing of the data control block, bit 2 of DCBEXCD2 
is set to 1 and the SYNAD routine is given control immediately. Otherwise, the SYNAD 
routine is given control when the next GET macro instruction is issued. 

Sequence Check: This condition is reported if a PUT macro instruction refers to a record 
whose key has a smaller numerical value than the key of the record previously referred to 
by a PUT macro instruction. The SYNAD routine is given control immediately; the 
record is not transferred to secondary storage. 
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Duplicate Record: This condition is reported if a PUT macro instruction refers to a record 
whose key duplicates that of the record previously referred to by a PUT macro 
instruction. The SYNAD routine is given control immediately; the record is not 
transferred to secondary storage. 

Data Control Block Closed When Error Routine Entered: This condition is reported if the 
control program's error recovery procedures encounter an uncorrectable output error 
during closing of the data control block. Bit 5 or 7 of DCBEXCD1 is set to 1, and the 
SYNAD routine is immediately given control. After appropriate analysis, the SYNAD 
routine must branch to the address in return register 14 so that the control program can 
finish closing the data control block. 

Overflow Record: This condition is reported if the input record is an overflow record. 

Incorrect Record Length: This condition is reported if the length of the record as 
specified in the record-descriptor word (RDW) is larger than the value in the 
DCBLRECL field of the data control block. 



Condition if On 

Record not found 

Record length check 

Space not found 

Invalid request — see bits 9-15 

Uncorrectable I/O error 

End of data 

Uncorrectable error 

Not read with-exclusive control 

Not used 

WRITE to input data set 

Extended search with DCBLIMCT=0 

Block or track requested was outside data set 

Tried to write capacity record 

Specified key as search argument when KEYLEN=0 or no 
key address supplied 

Request for options not in data control block 

Attempt to add fixed-length record with key beginning 
with hexadecimal FF 

Figure 3. Exception Code Bits — BDAM 

Notes for Figure 3: 

Record Not Found: This condition is reported if the search argument is not found in the 
data set. 

Record Length Check: This condition occurs for READ and WRITE (update) and 
WRITE (add). For WRITE (update) variable-length records only, the length in the BDW 
does not match the length of the record to be updated. For all remaining READ and 
WRITE (update) conditions the BLKSIZE, when 'S' is specified in the READ or 
WRITE macro, or the length given with these macros does not agree with the actual 
length of the record. For WRITE (add), fixed-length records, the BLKSIZE, when 'S' is 
specified in the WRITE macro, or the length given with this macro does not agree with 
the actual length of the record. For WRITE (add), all other conditions, no error can 
occur. 
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Exception 






Code Bit 


READ 


WRITE 





X 


X 


1 


X 


X 


2 




X 


3 


X 


X 


4 


X 


X 


5 


X 


X 


6 


X 


X 


7 




Type X 


8 






9 




X 


10 


X 


X 


11 


X 


X 


12 




X 


13 


X 


X 


14 


X 


X 


15 




X 



Space Not Found in Which to Add a Record: This condition occurs if either, there is no 
dummy record when adding an F-format record, or there is no space available when 
adding a V or U-format record. 

Invalid Request: Occurs whenever one of the following bits are set to one: 
Bit Meaning 

9 A WRITE was attempted for an input data set. 

10 An extended search was requested, but LIMCT was zero. 

1 1 The relative block or relative track requested was not in the data set. 

12 Writing a capacity record (R0) was attempted. 

13 A READ or WRITE with key was attempted, but either KEYLEN equaled zero or the key 
address was not supplied. 

14 The READ or WRITE macro request options conflict with the OPTCD or MACRF 
parameters. 

15 A WRITE (add) with fixed-length was attempted with the key beginning with X'FF". 

Uncorrectable Input/Output Error: This condition is reported if the control program's 
error recovery procedures encounter an uncorrectable error in transferring data between 
real and secondary storage. 

End of Data: This only occurs as a result of a READ (type DI, DIF, or DIX) when the 
record requested is an end-of-data record. 

Uncorrectable error: Same conditions as for bit 4. 

Not Read With Exclusive Control: A WRITE, type DIX or DKX, has occurred for which 
there is no previous corresponding READ with exclusive control. 

Register Bits Meaning 

0-7 Not used. 

8-31 Address of a work area containing the first 16 bytes of the IOB (after an 

uncorrectable input/output error caused by a GET, PUT, or PUTX macro 
instruction; original contents destroyed in other cases). If the error condition was 
detected before I/O was started, register contains all zeros. 

1 0-7 Not used. 

8-3 1 Address of the buffer containing the error record (after an uncorrectable 

input/output error caused by a GET, PUT, or PUTX macro instruction while 
attempting to read or write a data record; in other cases this register contains 0). 

2-13 0-31 Contents that existed before the macro instruction was issued. 

14 0-7 Not used. 

8-3 1 Return address. This address is either an address in the control program's Close 

routine (bit 2 of DCBEXCD2 is on), or the address of the instruction following the 
expansion of the macro instruction that caused the SYNAD routine to be given 
control (bit 2 of DCBEXCD2 is off). 

15 0-7 Not used. 

8-31 Address of the SYNAD routine. 

Figure 4. Register Contents on Entry to SYNAD Routine — QISAM 



194 OS/VS2 Data Management Macro Instructions 



Register Bits Meaning 

0-7 Not used. 

8-31 Address of the first IOB sense byte. (Sense information is valid only when associated 
with a unit check condition.) 

1 0-7 Not used. 

8-31 Address of the DECB. 

2-13 0-31 Contents that existed before the macro instruction was issued. 

14 0-7 Not used. 

8-31 Return address. 

15 0-7 Not used. 

8-3 1 Address of the SYNAD routine. 

Figure 5. Register Contents on Entry to SYNAD Routine — BISAM 



Register Bits Meaning 

0-7 Value to be added to the status indicators address to provide the address of the first 

CCW (QSAM only). 
8-3 1 Address of the associated data event control block for BDAM, BPAM, and BSAM; 
address of the status indicators shown in Figure 7 for QSAM. 

1 Bit is on for error caused by input operation. 

1 Bit is on for error caused by output operation. 

2 Bit is on for error caused by BSP, CNTRL, or POINT macro instruction (BPAM 
AND BSAM only). 

3 Bit is on if error occurred during update of existing record or if error did not prevent 
reading of the record. Bit is off if error occurred during creation of a new record or 
if error prevented reading of the record. 

4 Bit is on if the request was invalid. The status indicators pointed to in the data event 
control block are not present (BDAM, BPAM, and BSAM only). 

5 Bit is on if an invalid character was found in paper tape conversion (BSAM and 
QSAM only). 

6 Bit is on for a hardware error (BDAM only). 

7 Bit is on if no space was found for the record (BDAM only). 
8-31 Address of the associated data control block. 

2-13 0-31 Contents that existed before the macro instruction was issued. 

14 0-7 Not used. 

8-31 Return address. 

1 5 0-7 Not used. 

8-3 1 Address of the error analysis routine. 

Figure 6. Register Contents on Entry to SYNAD Routine— BDAM, BPAM, BSAM, and QSAM 
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Offset From 






IOB Address 






Byte 


Bit 


Meaning 


Name 


+2 



1 


Command reject 
Intervention required 


Sense byte 1 




2 


Bus-out check 






3 


Equipment check 






4 


Data check 






5 


Overrun 






6,7 


Device-dependent information; 
refer to the appropriate device 
manual 




+3 


0-7 


Device-dependent information; 
refer to the appropriate device 
manual 


Sense byte 2 



The following bytes make up the low-order seven bytes of 
the channel status word: 

+9 — Command address 

+ 12 



+ 13 






Attention 


Status byte 1 


1 


Status modifier 


(Unit) 


2 


Control unit end 




3 


Busy 




4 


Channel end 




5 


Device end 




6 


Unit check — must be on for 
sense bytes to be meaningful 




7 


Unit exception 







Program-controlled interrupt 


Status byte 2 


1 


Incorrect length 


(Channel) 


2 


Program check 




3 


Protection check 




4 


Channel data check 




5 


Channel control check 




6 


Interface control check 




7 


Chaining check 





+ 14 — Count field (2 bytes) 

Figure 7. Status Indicators for the SYNAD Routine— BDAM, BPAM, BSAM, and QSAM 

Note: If the sense bytes are X'lOFE', the control program has set them to this invalid 
combination because sense bytes could not be obtained from the device due to 
reoccurrence of unit checks. 
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APPENDIX B: DATA MANAGEMENT MACRO 
INSTRUCTIONS AVAILABLE BY ACCESS 
METHOD 



Macro Instruction 


BDAM 


BISAM 


BPAM 


BSAM 


QISAM 


QSAF 


BLDL 






X 








BSP 








X 






BUILD 


X 


X 


X 


X 


X 


X 


BUILDRCD 












X 


CHECK 


X 


X 


X 


X 






CHKPT 


X 


X 


X 


X 


X 


X 


CLOSE 


X 


X 


X 


X 


X 


X 


CNTRL 








X 




X 


DCB 


X 


X 


X 


X 


X 


X 


DCBD 


X 


X 


X 


X 


X 


X 


ESETL 










X 




FEOV 








X 




X 


FIND 






X 








FREEBUF 


X 


X 


X 


X 






FREEDBUF 


X 


X 










FREEPOOL 


X 


X 


X 


X 


X 


X 


GET 










X 


X 


GETBUF 


X 


X 


X 


X 






GETPOOL 


X 


X 


X 


X 


X 


X 


NOTE 






X 


X 






OPEN 


X 


X 


X 


X 


X 


X 


PDAB 












X 


PDABD 












X 


POINT 






X 


X 






PRTOV 








X 




X 


PUT 










X 


X 


PUTX 










X 


X 


READ 


X 


X 


X 


X 






RELEX 


X 












RELSE 










X 


X 


SETL 










X 




SETPRT 








X 




X 


STOW 






X 








SYNADAF 


X 


X 


X 


X 


X 


X 


SYNADRLS 


X 


X 


X 


X 


X 


X 


TRUNC 












X 


WAIT 


X 


X 


X 


X 






WRITE 


X 


X 


X 


X 







XLATE 



Appendix B: Data Management Macro Instructions Available by Access Method 197 



APPENDIX C: DEVICE CAPACITIES 



The following information provides a guide to coding the block size (BLKSIZE) and 
logical record length (LRECL) operands in the DCB macro instruction. These values can 
be used to determine the maximum block size and logical record length for a given 
device, and they can be used to determine the optimum blocking factor when records are 
to be blocked. 



Card Readers and Card Punches 



Printers 



Format F, V, or U records are accepted by readers and punches but the logical record 
length for a card reader or card punch is fixed at 80 bytes. The logical record length for 
an IBM 2596 Card Reader is 96 bytes. If the optional control character is specified, the 
logical record length is 81 (the control character is not part of the data record). If card 
image mode is used, the buffer required to contain the data must be 160 bytes. 



The following shows the record length that can be specified for the various printers. In 
some cases, two values are shown; except for the 3800, the larger of the two values 
requires that an optional feature be installed on the printer being used. If the optional 
control character is specified to control spacing and skipping, the record length is 
specified as one greater than the actual data length (the control character is not part of 
the data record). 

1403 printer — 120 or 132 bytes 

1443 printer — 120 or 144 bytes 

3211 printer — 132 or 150 bytes 

1052 printer keyboard — 130 bytes (supported only by the EXCP access method) 

3210 printer keyboard — 130 bytes (supported only by the EXCP access method) 

3215 printer keyboard — 130 bytes (supported only by the EXCP access method) 

3525 card punch, 

print feature — 64 bytes 

3800 printer — 136 bytes for 10 pitch 

163 bytes for 12 pitch 
204 bytes for 15 pitch 



Paper-Tape Reader 

2671 paper tape — 32,760 bytes 

Magnetic-Tape Units 

2400/3400 magnetic-tape units — 32,760 
(7 tracks and 9 tracks) 
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Direct-Access Devices 



The following table shows the capacity of direct-access devices by track, cylinder, and 
total capacity in bytes. 





Volume 


Maximum Block- 


Tracks/ 


Number of 




Device 


Type 


size/Track 1 


Cylinder 


Cylinders 2 


Total Capacity 1,2 


2305-1 


Drum 


14136 


8 


48 


5,428,224 


2305-2 


Drum 


14660 


8 


96 


11,258,880 


2314/2319 


Disk 


7294 


20 


200 


29,176,000 


3330/3333 












(Model 1)3 


Disk 


13030 


19 


404 


100,018,280 


3330/3333 












(Model 11) 


Disk 


13030 


19 


808 


200,036,560 


3340/3344 


Disk 


8368 


12 


696 
(70-megabytes) 

348 
(35-megabytes) 


69,889,536 
34,944,768 


3350 


Disk 


19069 


30 


555 


317,498,850 



' Capacity indicated in bytes (when R0 is used by the IBM programming system). 
2 Excluding alternate cylinders. 

■>The Mass Storage System (MSS) virtual volumes assume the 
characteristics of the 3330/3333, Model 1. 

Each record written on a direct-access device requires some "device overhead." The 
term device overhead means the space required by the device for address markers, count 
areas, gaps between the count, key, and data areas, and gaps between blocks. The 
following formulas can be used to compute the number of bytes required for each data 
block including the space required for device overhead. Note that any fraction of a byte 
must be ignored. For example, if the formula computation results in 15.644 bytes, 15 
bytes must be used to determine track capacity. 







Track 


Bytes Required by Each 1 


Data Block 


Device 




Capacity 


Blocks With Keys 


Blocks Without Keys 


2305-1 




14568 1 


634+KL+DL 


432+DL 


2305-2 




14858' 


289+KL+DL 


198+DL 


2314/2319 




7294 


146+(KL+DL)534/512 2 


101 + (DL)534/5123 


3330/3333 










(Model 1 or 


ll) 4 


13165 1 


191+KL+DL 


135+DL 


3340/3344 




8535 1 


242+KL+DL 


167+DL 


3350 




19254 


267+KL+DL 


185+DL 



DL is data length. 
KL is key length. 

'This value is different from the maximum block size per track because the 

formula for the last block on the track includes an overhead f6r this device. 
2 The formula for the last block on the track is 45+KL+DL. 
^The formula for the last block on the track is DL. 
4 The Mass Storage System (MSS) virtual volumes assume the characteristics 

of the 3330/3333, Model 1. 

When the track-overflow feature is being used or variable-length spanned records are 
written, the size of a data block or logical record can exceed the capacity of a single track 
on the direct-access device used. 
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APPENDIX D: DCB EXIT LIST FORMAT AND 
CONTENTS 



The following shows the format and contents that must be supplied by the problem 
program when the EXLST operand is specified in a DCB macro instruction. The exit list 
must begin on a fullword boundary and each entry in the list requires one fullword. 



3-Byte Routine Address — Purpose 

Ignored; the entry is not active. 

Process a user input header label. 

Create a user output header label. 

Process a user input trailer label. 

Create a user output trailer label. 

Data control block exit routine. 

End-of-volume exit routine. 

Pointer to user's totaling area. 

Block count unequal exit routine. 

Defer processing of a user input trailer label 

from the end-of-data until the CLOSE macro 

instruction is issued. 

Defer processing a nonstandard input trailer 

label on magnetic tape unit from the 

end-of-data until the CLOSE macro instruction 

is issued (no exit routine address). 

Define an FCB image. 

Allow analysis of ABEND condition and select 

one of several options. 

Address of the PDAB for which this DCB 

is a member 

Take an exit during open to allow user to examine 

JCL-specified setup requirements for a 3800 printer. 

This exit is mutually exclusive with the DCB exit; if 

both exits are required, you must use the JFCBE exit. 

Last entry in list. A high-order bit can be 

specified with any of the above codes but must 

always be specified with the last entry. 





Hexadecimal 


Routine Type 


Code 


Inactive entry 


00 


Input header label 


01 


Output header label 


02 


Input trailer label 


03 


Output trailer label 


04 


Data control block exit 


05 


End-of-volume 


06 


User totaling 


0A 


Block count exit 


0B 


Defer input trailer 


OC 


label 




Defer nonstandard 


0D 


input trailer label 




FCB Image 


10 


DCB ABEND exit 


II 


QSAM parallel input 


12 


JFCBE 


15 



Last entry 



80 



The list can be dynamically shortened during execution by setting the high-order bit of a 
word to a value of 1. An entry in the list can be made inactive dynamically by setting the 
high-order byte of the word to a value of hexadecimal 00 or 80. 

When control is passed to an exit routine, the general registers contain the following 
information: 

Register Contents 

Variable; the contents depend on the exit routine used. 

1 The three low-order bytes contain either the address of the DCB 
currently being processed or, when certain exits are taken, the 
address of the exit parameter list. These exits are: user-label 
exits (X'OI'-W), deferred nonstandard input trailer exit 
(X'OD'), and DCB ABEND exit (X'l I'). 

2-13 Contents prior to execution of the macro instruction. 

14 Return address (must not be altered by the exit routine). 

15 Address of the exit routine entry point. 

The conventions for saving and restoring registers are as follows: 

• The exit routine must preserve the contents of register 14. It need not preserve the 
contents of other registers. The control program restores registers 2-13 before 
returning control to the problem program. 
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• The exit routine must not use the save area whose address is in register 13, because 
this area is used by the control program. If the exit routine calls another routine or 
issues supervisor or data management macro instructions, it must provide the address 
of a new save area in register 13. 

For a detailed description of each exit list processing option, refer to OS/VS2 MVS 
Data Management Services Guide. 
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APPENDIX E: CONTROL CHARACTERS 



Machine Code 



Each logical record, in all record formats, can contain an optional control character. This 
control character is used to control stacker selection on a card punch or card read punch, 
or it is used to control printer spacing and skipping. If a record containing an optional 
control character is directed to any other device, it is considered to be the first data byte, 
and it does not cause a control function to occur. 

In format-F and format-U records, the optional control character must be in the first 
byte of the logical record. 

In format-V records, the optional control character must be in the fifth byte of the 
logical record, immediately following the record descriptor word of the record. 

Two control character options are available. A control character option is selected by 
coding the appropriate character in the RECFM operand of the DCB macro instruction. 
If either option is specified in the data control block, a control character must be 
included in each record, and other spacing or stacker selection options also specified in 
the data control block are ignored. 



The record format field in the data control block indicates that the machine code control 
character has been placed in each logical record. If the record is written, the appropriate 
byte must contain the command code bit configuration specifying both the write and the 
desired carriage or stacker select operation. 

The machine code control characters for a printer are as follows: 

Act Immediately — No Printing 
(Code in Hexadecimal) 



Print and Then Act 




Act 


(Code in Hexadecimal) 


Action 


(CO! 


01 


Print only (no space) 




09 


Space 1 line 


OB 


11 


Space 2 lines 


13 


19 


Space 3 lines 


IB 


89 


Skip to channel 1 


8B 


91 


Skip to channel 2 


93 


99 


Skip to channel 3 


9B 


Al 


Skip to channel 4 


A3 


A9 


Skip to channel 5 


AB 


Bl 


Skip to channel 6 


B3 


B9 


Skip to channel 7 


BB 


CI 


Skip to channel 8 


C3 


C9 


Skip to channel 9 


CB 


Dl 


Skip to channel 10 


D3 


D9 


Skip to channel 1 1 


DB 


El 


Skip to channel 12 


E3 
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The machine code control characters for a card read punch device are as follows: 

Code in Hexadecimal Action 

01 Select stacker 1 

41 Select stacker 2 

81 Select stacker 3 

Other command codes for specific devices are contained in IBM System Reference Library publications 
describing the control units or devices. 

American National Standards Institute Control Characters 

In place of machine code, control characters defined by the American National Standards 
Institute (ANSI) can be specified. These characters must be represented in EBCDIC 
code. 

American National Standards Institute (ANSI) control characters are as follows: 

Code Action Before Printing a Line 



b 


Space one line (blank code) 





Space two. lines 


- 


Space three lines 


+ 


Suppress space 


i 


Skip to channel 1 


2 


Skip to channel 2 


3 


Skip to channel 3 


4 


Skip to channel 4 


5 


Skip to channel 5 


6 


Skip to channel 6 


7 


Skip to channel 7 


8 


Skip to channel 8 


9 


Skip to channel 9 


A 


Skip to channel 10 


B 


Skip to channel 1 1 


C 


Skip to channel 12 


Code 


Action After Punching a Card 


V 


Select punch pocket 1 


W 


Select punch pocket 2 



These control characters include those defined by ANSI FORTRAN. If any other 
character is specified, it is interpreted as 'b' or V, depending on the device being used; no 
error indication is returned. 
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APPENDIX F: DATA CONTROL BLOCK 
SYMBOLIC FIELD NAMES 



The following describes data control block fields that contain information which defines 
the data characteristics and device requirements for a data set. Each of the fields 
described shows the values that result from specifying various options in the DCB macro 
instruction. These fields can be referred to by the problem program through the use of a 
DCBD macro instruction which creates a dummy control section (DSECT) for the data 
control block. Fields that contain addresses are 4 bytes long and are aligned on a 
fullword boundary. If the problem program inserts an address into a field, the address 
must be inserted into the low-order 3 bytes of the field without changing the high-order 
byte. 

The contents of some fields in the data control block depend on the device and access 
method being used. A separate description is provided when the contents of the field are 
not common to all device types and access methods. 



Data Control Block — Common Fields 

Bytes and Field 

Offset Alignment Name 



26(1A) 2 



40(28) 8 

40(28) 2 

42(2A) 2 

45(2D) .3 

48(30) 1 



DCBDSORG 



...X XX.. 

1. 

1 

DCBDDNAM 

DCBTIOT 

DCBMACRF 

DCBDEBA 

DCBOFLGS 
...1 .... 
1... 

0. 



Description 

Data set organization. 



Code 
IS 
PS 
DA 

PO 
U 



Indexed sequential. 

Physical sequential. 

Direct organization. 

Reserved bits. 

Partitioned organization. 

Unmovable — the data set contains 

location-dependent information. 



Eight byte name of the data definition statement that 
defines the data set associated with this DCB. (Before 
DCB is opened.) 

(After DCB is opened.) Offset from the TIOT origin to 
the TIOELNGH field in the TIOT entry for the DD 
statement associated with this DCB. 

This field may only be referenced during and after OPEN. 
It is common to all uses of the DCB and is created by 
moving the DCBMACR field into this area. 

(After DCB is opened.) Address of the associated DEB. 

Flags used by Open routine. 

OPEN has completed successfully. 

Set to 1 by problem program to indicate 

concatenation of unlike attributes. 

Set to by an I/O support function when that 

function takes a user exit. It is set to to 

inhibit other I/O support functions from 

processing this DCB. 

Set to 1 on return from the user exit to the 

I/O support function that took the exit. 
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Offset 

50(32) ..2 



Bytes and 
Alignment 



Field 
Name 

DCBMACR 

(Before 

OPEN) 



Description 

Macro instruction reference before OPEN. 
Major macro instructions and various options 
associated with them. Used by the Open routine to 
determine access method. Used by the access method 
executors in conjunction with other parameters to 
determine which load modules are required. This field is 
moved to overlay part of DCBDDNAM at Open time and 
becomes the DCBMACRF field. 

This field is common to all uses of the DCB, but each 
access method must be referenced for its meaning. 



Data Control Block— BPAM, BSAM, QSAM 



Offset 

20(14) 

21(15) 
24(18) 

32(20) 



32(20) 



Bytes and 
Alignment 



Field 
Name 

DCBBUFNO 



DCBBUFCB 
DCBBUFL 

DCBBFALN 

xx 

10 

01 

DCBBFTEK 

.XXX .... 

.1.0 .... 
.0.1 .... 
.110 .... 



.010 



Description 

Number of buffers required for this data set. May range 
from to a maximum of 255. 

Address of buffer pool control block. 

Length of buffer. May range from to a maximum of 
32,760. 



Buffer alignment: 
D Doubleword boundary. 

F Fullword not a doubleword boundary, 

coded in the DCB macro instruction. 



Buftering technique: 
S Simple buffering. 

E Exchange buffering. 

A QSAM locate mode processing of spanned 

records: OPEN is to construct a record area if it 

automatically constructs buffers. 

R BSAM create BDAM processing of unblocked 

spanned records: Software track overflow. OPEN 
forms a segment work area pool and stores the 
address of the segment work area control block in 
DCBECBW. However, WRITE uses a segment 
work area to write a record as one or more 
segments. 

BSAM input processing of unblocked spanned 
records with keys: Record offset processing. 
READ reads one record segment into the record 
area. The first segment of a record is preceded in 
the record area by the key. Subsequent segments 
are at an offset equal to the key length. 



33(21) 


.3 


x... 
DCBEODAD 


Reserved bit. 

End-of-data address. Address of a userprovidedrovided 
routine to handle end-of-data conditions. 


36(24) 


1 


DCBRECFM 


Record format. 








Code 








001 


D 


Format-D record. 






10 


F 


Fixed record length. 






01. 


V 


Variable record length. 






11 

..1 

...1 .... 


U 
T 
B 


Undefined record length. 

Track overflow. 

Blocked records. May not occur with undefined 

(U). 
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Offset 



Bytes and 
Alignment 



37(25) .3 
42(2A) 2 



50(32) 



..2 



51(33) 



50(32) 



51(33) 



Field 
Name 

I. 



10. 

01. 

00. 

1 



DCBEXLST 
DCBMACRF 



DCBMACR 

(Before 

OPEN) 



Description 

S Fixed length record format: Standard blocks. (No 

truncated blocks or unfilled tracks are embedded 
in the data set.) Variable length record format: 
Spanned records. 
A ANSI control character. 

M Machine control character. 

No control character. 
Key length (K.EYLEN) was specified in the DCB macro 
instruction. This bit is inspected by the Open routine to 
prevent overriding a specification of KEYLEN=0 by a 
nonzero specification in the JFCB or data set label. 

Exit list. Address of a user-provided exit list control block. 

Macro instruction reference after OPEN. 

Contents and meaning are the same as those of the 
DCBMACR field in the foundation segment before 
OPEN. 

Major macro instructions and various options 
associated with them. Used by the Open 
routine to determine access method. Used by the access 
method executors in conjunction with other parameters to 
determine which load modules are required. 

Code 



Byte 1 




BS AM— Input 


00 




Always zero for BSAM. 


..1 


R 


READ 


...X X..X 




Reserved bits. 


1.. 


P 


POINT (which implies NOTE) 


1. 


C 


CNTRL 


Byte 2 




BSAM— Output 


00 




Always zero for BSAM. 


..1 


W 


WRITE 


1... 


L 


Load mode BSAM (create BD/ 
set). 


1.. 


P 


POINT (which implies NOTE) 


I. 


C 


CNTRL 



BSAM create BDAM processing of unblocked 
spanned records, with BFTEK = R specified: The 
user's program has provided a segment work area 
pool and stored the address of the segment work 
area control block in DCBEOBW. 



Byte 1 




QS AM— Input 







Always zero for QSAM 


.1 


G 


GET 


..0 




Always zero for QSAM 


...1 


M 


Move mode. 


1... 


L 


Locate mode. 


1.. 


T 


Substitute mode. 


1. 


C 


CNTRL 


1 


D 


Data mode. 


Byte 2 




QSAM— Output 







Always zero for QSAM 


.1 


P 


PUT 


..0 




Always zero for QSAM 


...1 .... 


M 


Move mode. 


1... 


L 


Locate mode. 


1.. 


T 


Substitute mode. 


1. 


C 


CNTRL 


1 


D 


Data mode. 
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Offset 


Bytes and 
Alignment 


Field 
Name 


Description 


50(32) 






Byte 1 

00 

..1 

1.. 

...X x.xx 


R 
P 


BPAM— Input 

Always zero for BPAM. 

READ 

POINT (which implies NOTE) 

Reserved bits. 


51(33) 






Byte 2 

00 

..1 

1.. 

...X x.xx 


A 
W 
P 


BPAM— Output 

Always zero for BPAM. 

WRITE 

POINT (which implies NOTE), 

Reserved bits. 



Direct-Access Storage Devices Interface 



Offset 

16(10) 
17(11) 



Bytes and 
Alignment 



Magnetic Tape Interface 



Offset 

16(10) 



Bytes and 
Alignment 



17(11) 



18(12) 



Field 
Name 

DCBKEYLE 

DCBDEVT 

0010 0110 

0010 0111 

0010 1000 

0010 1001 

0010 1101 
0010 1010 
0010 1011 



Field 
Name 

DCBTRTCH 



0010 0011 

0011 1011 
0001 0011 
0010 1011 

DCBDEVT 

1000 0001 
1000 0011 

DCBDEN 



0000 0011 

0100 0011 

1000 0011 

1100 0011 



Description 

Key length of the data set. 

Device type. 

2305 Disk Storage Facility, Model 1. 

2305 Disk Storage Facility, Model 2. 

2314 Disk Storage Facility. 

3330 Disk Storage, Model 1, or Mass Storage System 

(MSS) virtual volume. 

3330 Disk Storage, Model 11. 

3340/3344 Disk Storage. 

3350 Direct Access Storage. 



Description 

Tape recording technique for 7-track tape. 



Code 

E 
T 
C 
ET 



Even parity. 

BCD/EBCDIC translation. 
Data conversion. 
Even parity and translation. 



Device type. 

2400 series magnetic tape unit (7-track or 9-track). 
3400 series magnetic tape unit. 

Tape density — 2400 series magnetic tape units. 

9-tracks 



Code 


1 

2 
3 
4 



7-tracks 

200 BPI 
556 BPI 
800 BPI 



800 BPI 
1600 BPI 
6250 BPI 
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Paper Tape Interface 





Bytes 


and 


Field 






Offset 


Alignment 


Name 


Description 


16(10) 


1 




DCBCODE 


Paper tape code being used. Th 
table is made available. 










Code 










1000 0000 


N 


No conversion 








0100 0000 


I 


IBM BCD 








0010 0000 


F 


Friden 








0001 0000 


B 


Burroughs 








0000 1000 


C 


National Cash Register 








0000 0100 


A 


ASCII (8-t rack) 








0000 0010 


T 


Teletype 1 


17(11) 


.1 




DCBDEVT 


Device 


type. 








0101 0000 


2671 Paper Tape Reader. 



Card Reader, Card Punch Interface 





Bytes 


and 


Field 




Offset 


Alignment 


Name 


Description 


16(10) 


1 




DCBMODE,DCBSTACK 










Code 








xxxx .... 


Mode of operation for 1442 Card Read 
Punch. 








1000 .... 


C Column binary mode. 








0100 .... 


E EBCDIC mode. 








xxxx 


Stacker selection. 








0001 


1 Stacker 1. 








0010 


2 Stacker 2. 


17(11) 


.1 




DCBDEVT 

0100 0011 
0100 0001 
0100 0010 
0100 0100 
0100 0101 
0100 0110 
0100 MOO 


Device type. 

1442 Card Read Punch 
2540 Card Reader 
2540 Card Punch 
2501 Card Reader 
2520 Card Read Punch 
3505 Card Reader 
3525 Card Punch 



'Trademark of Teletype Corporation. 
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Printer Interface 



Offset 


Bytes and 
Alignment 


Field 
Name 


Description 


16(10) 


1 




DCBPRTSP 

0000 0001 

0000 1001 

0001 0001 
0001 1001 


Number indicating norm; 

Code 

No spacing. 

1 Space one line. 

2 Space two lines. 

3 Space three lines. 


17(11) 


.2 




DCBDEVT 

ByteO 
0100 1000 
0100 1001 
0100 1010 
0100 1110 


Device type. 

1403 Printer 
3211 Printer 
1443 Printer 
3800 Printing Subsystem 



19(13) ...1 



Byte 1 
0010 0000 
0001 0000 
DCBPRBYT 
xxxx xx.. 
II 



Access Method Interface 
BSAM, BPAM Interface 



1.. 



..l 

...1 .... 



57(39) .3 
62(3E) ..2 



DCBSYNAD 
DCBBLKSI 



Test-for-printer-overflow mask (PRTOV mask). If printer 
overflow is to be tested for, the PRTOV macro instruction 
sets the mask as follows: 



Code 

9 
12 



Test for channel 9 overflow. 
Test for channel 12 overflow. 



Reserved. 

Bits to identify presently active table reference character 

when 3800 printer is operating under OPTCD=J. 





Bytes and 


Field 




Offset 


Alignment 


Name 


Description 


52(34) 


1 


DCBOPTCD 
1 


Option codes, 

Code 

W Write 



1... Q 
.1.. Z 


..1. T 
...1 J 



Write-validity check (DASD). 
U Allow a data check caused by an invalid 

character. (1403 printer with UCS feature.) 
B Treat EOF and EOV labels as EOV labels which 

allows SL or AL tapes to be read out of order. 

(Magnetic tape.) 
C Chained scheduling. 

H Optical Reader: Hopper empty exit. 

Input Tape Files: Requests the testing for and 

bypassing of any embedded DOS checkpoint 

records encountered. (This code can only be 

specified in a JCL statement.) 

An ASCII data set is to be processed. 

Magnetic tape devices: Use reduced error 

recovery procedure. 

BSAM only: user totaling. 

Specifies that the first data byte in the output data 

line will be a 3800 table reference character for 

dynamic selection of character sets. 

Address of user's synchronous error routine to be entered 
when a permanent error occurs. 

Maximum block size. Maximum value: 32,760. For 
fixed-length blocked record format, it must be a multiple 
of the length given in DCBLRECL. For variable-length 
records, this must include the 4 byte block length field. 
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Bytes and 


Field 


Offset 


Alignment 


Name 


72(48) 


1 


DCBNCP 


80(50) 


1 


DCBUSASI/ 
DCBLBP 



81(51) .1 
82(52) ..2 



.1 

DCBBUFOF 
DCBLRECL 



Page of GC26-3873-0 

As Updated March 30, 1979 

By TNL GN26-0941 



Description 



Number of chained programs. Number of READ or 
WRITE requests which may be issued prior to a CHECK. 
Maximum number: 99. 

ASCII tape. 
Block prefix. 

Block prefix is a four-byte field containing the block 
length. 

Block prefix length. 

Logical record length. For fixed-length blocked record 
format, the presence of DCBLRECL allows BSAM to 
read truncated records. For undefined records, this field 
contains block size. 



QSAM Interface 



Offset 

52(34) 



Bytes and 
Alignment 



Field 
Name 

DCBOPTCD 



1... 
.1.. 



.1 

..1 .... 



57(39) 
62(3E) 

80(50) 



81(51) 
82(52) 



1.. 

1. 

1 

DCBSYNAD 

DCBBLKSI 



DCBUSASI/ 
DCBLBP 

.1 



DCBBUFOF 
DCBLRECL 



Description 

Option codes. 



Code 

W 

u 



Write-validity check (DASD). 

Allow a data check for an invalid character (1403 

with UCS). 

Window processing requested. (MSS) 

Treat EOF and EOV labels as EOV labels which 

allows SL or AL tapes to be read out of order 

(magnetic tape). 

Chained scheduling. 

Online correction. 

Input Tape Files: Requests the testing for and 

bypassing of any embedded DOS checkpoint 

records encountered. (This code can only be 

specified in a JCL statement.) 

An ASCII data set is to be processed. Same as 

DCBOPTQ. BSAM only. 

Magnetic tape devices. Use reduced error 

recovery procedure. 

User totaling. 

Specifies that the first data byte in the output data 

line will be a 3800 table reference character. 



Address of the user's synchronous error routine to be 
entered when a permanent error occurs. 

Maximum block size. Maximum value: 32,760. For 
fixed-length blocked record format, it must be a multiple 
of DCBRECL. For variable-length records this must 
include the 4-byte block length field provided by the 
access method. 

ASCII tape. 
Block prefix. 

Block prefix is a four-byte field containing the block 
length. 

Block prefix length. 

Format-F records: Record length. 
Format-U records: Block size. 
Format-V records — 
• Unspanned record format — 

GET: PUTX; record length. 

PUT: Actual or maximum record length. 
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Bytes and 


Field 




Offset 


Alignment 


Name 


Description 

• Spanned record format — 
Locate mode — 

- GET: Segment length. 

- PUT: Actual or minimum segment 
length. 

Logical record interface — 

- Before OPEN: Maximum logical record 
length. 

- After GET: Record length. 

- Before PUT: Actual or maximum record 
length. 

Move mode — 

- GET: Record length. 

- PUT: Actual or maximum record length. 

• Data mode, GET — 

Data records up to 32,752 bytes: Data 

length. 

Data records exceeding 32,752 bytes: 

- Before OPEN: X'8000' 

- After OPEN: Data length. 

• Output mode, PUTX (output data set): 
Segment length. 


84(54) 


1 


DCBEROPT 


Error option. Disposition of permanent errors if the user 
returns from a synchronous error exit (DCBSYNAD), or 
if the user has no synchronous error exit. 






100 


ACC: Accept. 






010 


SKP: Skip. 






001 


ABE: Abnormal end of task. 






...X xxxx 


Reserved bits. 


85(55) 


3 


DCBCNTRA 


Address of CNTRL module. 


88(58) 


2 




Reserved. 


90(5A) 


2 


DCBPRECL 


Block length, maximum block length or data length. 


92(5C) 


4 


DCBEOB 


Address of end of block module. 



Data Control Block— ISAM 



Offset 

16(10) 
17(11) 



Bytes and 
Alignment 



20(14) 1 
21(15) .3 
24(18) 2 



Field 

Name Description 

DCBKEYLE Key length. 

DCBDEVT Device type. 

0000 0110 2305 Disk Storage Facility, Model 1. 

0000 0111 2305 Disk Storage Facility, Model 2. 

0000 1000 23 14 Disk Storage Facility. 

0000 1001 3330 Disk Storage, Model 1, or 

Mass Storage System (MSS) 

virtual volume. 

0000 1101 3330 Disk Storage, Model 11. 

0000 1010 3340 Disk Storage. 

0000 1011 3350 Direct Access Storage. 

DCBBUFNO Number of buffers required for this data set: 0-255. 

DCBBUFCB Address of buffer pool control block. 

DCBBUFL Length of buffer: 0- 32,760. 
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Offset 



32(20) 



Bytes and 
Alignment 



33(21) 



36(24) 



37(25) 
42(2A) 



50(32) 



50(32) 



51(33) 



50(32) 



Field 
Name 

DCBBFALN 



xx 

10 

01 

II 

DCBEODAD 

DCBRECFM 



10.. 
10.. 
II.. 
..I. 

...I 



Description 



DCBEXLST 
DCBMACRF 



DCBMACR 



Code 

D 

F 



Buffer alignment: 

Doubleword boundary. 

Fill I word not a doubleword boundary, coded in 

the DCB macro instruction. 

Fullword not a doubleword boundary, coded in 
the DD statement. 



Address of a user-provided routine to handle end-of-data 
conditions. 

Record format. 



Code 
F 

V 

u 

T 
B 



10. 


A 


01. 


M 


00. 

..1 





Fixed length records. 

Variable length records. 

Undefined length records. 

Track overflow. 

Blocked records. May not occur with undefined 

(U). 

Standard records. No truncated blocks or unfilled 

tracks are embedded in the data set. 

ANSI control character. 

Machine control character. 

No control character. 

Key length (KEYLEN) was specified in the DCB 

macro instruction; this bit is inspected by the 

Open routine to prevent overriding a specification 

of KEYLEN=0 by a nonzero specification in the 

JFCBordataset label. 

Exit list. Address of a user-provided list. 

Macro instruction reference after OPEN: 

Contents and meaning are the same as those of the 
DCBMACR field before OPEN. 

Macro instruction reference before OPEN: specifies the 
major macro instructions and various options associated 
with them. Used by the Open routine to determine access 
method. Used by the access method executors in 
conjunction with other parameters to determine which 
load modules are required. 









Code 


Byte 


1 




BIS AM 


00.0 


0... 




Always zero for BISAM. 


..1. 




R 


READ 




.1.. 


S 


Dynamic buffering. 




..1. 


C 


CHECK 




...X 




Reserved bit. 


Byte 


2 




BISAM 


00.0 


0000 




Always zero for BISAM. 


..1. 




w 


WRITE 


Byte 


1 




QISAM 


0.0. 


.0.. 




Always zero for QISAM. 


.1.. 




G 


GET 


...1 




M 


Move mode of GET. 




1... 


L 


Locate mode for GET. 




..XX 




Reserved bits. 
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Offset 



51(33) 



52(34) 



Bytes and 


Field 






Alignment 


Name 


Description 




Byte 2 




QISAM 




1 


S 


SETL 




.1.. .... 


P 


PUT or PUTX. 




..0 




Always zero for QISAM. 




...1 .... 


M 


Move mode of PUT. 




1... 


L 


Locate mode of PUT. 




1.. 


U 


Update in place (PUTX). 




1. 


K 


SETL by key. 




1 


I 


SETL by ID. 


1 


DCBOPTCD 


Option 
Code 


codes: 




1 


W 


Write-validity check. 




.1 


U 


Full-track index write. 




..1 

...1 .... 


M 
I 


Master indexes. 
Independent overflow area 




1... 


Y 


Cylinder overflow area. 




1. 


L 


Delete option. 




1 


R 


Reorganization criteria. 




X.. 




Reserved bit. 



53(35) 



54(36) ..1 



55(37) 



56(38) 4 

60(3C) 2 

62(3E) ..2 

64(40) 4 

68(44) 2 

70(46) 2 

72(48) 1 

73(49) .3 



DCBMAC 



xxxx ...X 



DCBNTM 



DCBCYLOF 



Extension of the DCBMACRF field for ISAM. 



DCBSYNAD 

DCBRKP 

DCBBLKSI 
DCBMSWA 

DCBSMSI 

DCBSMSW 

DCBNCP 

DCBMSHI 



Code 

U 
U 
A 



Reserved bits. 
Update for read. 
Update type of write. 
Add type of write. 



Number of tracks that determines the development of a 

master index. 

Maximum permissible value: 99. 

The number of tracks to be reserved on each prime data 
cylinder for records that overflow from other tracks on 
that cylinder. Refer to the section on allocating space for 
an ISAM data set in OS/VS2 MVS Data Management 
Services Guide to determine how to calculate the 
maximum number. 

Address of user's synchronous error routine to be entered 
when uncorrectable errors are detected in processing data 
records. 

Relative position of the first byte of the key within each 
logical record. Maximum permissible value: logical record 
length minus key length. 

Block size. 

Address of the storage work area reserved for use by the 
control program when new records are being added to an 
existing data set. 

Number of bytes in area reserved to hold the highest level 
index. 

Number of bytes in work area used by control program 
when new records are being added to the data set. 

Number of copies of the READ-WRITE (type K.) channel 
programs that are to be established for this data control 
block (99 maximum). 

Address of the storage area holding the highest level 
index. 
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Bytes and 
Offset Alignment 

80(50) I 



81(51) .1 



82(52) ..2 



197(C5) .1 



Field 

Name Description 

DCBEXCDI First byte in which exceptional conditions delected in 

processing data records are reported to the user. 

I Lower key limit not found. 

I Invalid device address for lower limit. 

1 Space not found. 

.1 .... Invalid request. 

I... Uncorrectable input error. 

. I.. Uncorrectable output error. 

..I. Block could not be reached (input). 
1 Block could not be reached (update). 

DCBEXCD2 Second byte in which exceptional conditions detected in 

processing data records are reported to the user. 

I Sequence check. 

.1 Duplicate record. 

..I DCB closed when error was detected. 

...1 .... Overflow record. 

I... PUT: length field of record larger than 
length indicated in DCBLRECL. 
xxx Reserved bits. 

DCBLRECL Logical record length for fixed-length record formats. 

Variable-length record formats: maximum logical record 
length or an actual logical record length changed 
dynamically by the user when creating the data set. 

DCBOVDEV Device type for independent overflow. 

0000 0110 2305 Disk Storage Facility, Model I. 

0000 01 1 1 2305 Disk Storage Facility, Model 2. 

0000 1000 2314 Disk Storage Facility. 

0000 1001 3330 Disk Storage, Model I, or 

Mass Storage System (MSS) 

virtual volume. 
0000 1 101 3330 Disk Storage, Model II. 

0000 1010 3340/3344 Disk Storage. 

0000 ION 3350 Direct Access Storage. 



Data Control Block — BDAM 





Bytes and 


Field 


Offset 


Alignment 


Name 


16(10) 


1 


DCBKEYLE 


17(11) 


.3 


DCBREL 


20(14) 


1 


DCBBUFNO 


21(15) 


.3 


DCBBUFCB 


24(18) 


2 


DCBBUFL 


32(20) 


1 


DCBBFALN 

..XX 

10 

01 



Description 

Key length. 

Number of relative tracks or blocks in this data set. 

Number of buffers required for this data set. May range 
from to 255. 

Address of buffer pool control block or of dynamic buffer 
pool control block. 

Length of buffer. May range from to 32,760. 



Buffer alignment: 

Doubleword boundary. 

Fullword not a doubleword boundary, coded in 

the DCB macro instruction. 

Fullword not a doubleword boundary, coded in 

the DD statement. 

Reserved bits. 
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Bytes and 


Field 




Offset 


Alignment 


Name 


Description 


32(20) 


1 


DCBBFTEK 








..x 

..1 


Bu 
R Un 



36(24) 



37(25) 
42(2A) 



50(32) 



50(32) 



.3 
..2 



51(33) 



DCBRECFM 

10 

01 

11 

1 

.1 .... 

1... 

.00. 
1 



DCBEXLST 
DCBMACRF 



DCBMACR 



Byte 1 

00 

..1 

...1 .... 

1... 

1.. 



Byte 2 

00 

..1 

...1 


1... 

X.. 

.... ..1. 

1 



Buffering technique. 

Unblocked spanned records: Software track 
overflow. OPEN forms a segment work area pool. 
The number of segment work areas is determined 
by DCBBUFNO (OPEN stores the address of the 
segment work area control block in DCBDYNB) 
if dynamic buffering is not used or in the dynamic 
buffer pool control block (see DCBBUFCB) if 
dynamic buffering is used. WRITE uses a segment 
work area to write a record as one or more 
segments. READ uses a segment work area to 
read a record that was written as one or more 
segments. 



Record format. 



Code 

F 

V 

U 
T 

B 
S 



Fixed record length. 
Variable record length. 
Undefined record length. 
Track overflow. 

Blocked (allowed only with V). 
Spanned (allowed only with V). 
Always zeros. 

Key length (KEYLEN) was specified in the DCB 
macro instruction. This bit is inspected by the 
Open routine to prevent overriding a specification 
of KEYLEN=0 by a nonzero specification in the 
JFCB or data set label. 

Exit list. Address of a user-provided exit list control block. 

Macro instruction reference after OPEN. 

Contents and meaning are the same as DCBMACR before 
OPEN. 

Macro instruction reference before OPEN: major macro 
instructions and various options associated with them that 
will be used. 



Code 

R 
K 
I 
S 

X 
C 

Code 

W 
K 
I 



Always zero for BDAM. 

READ 

Key segment with READ. 

ID argument with READ. 

System provides area for READ (dynamic 

buffering). 

Read exclusive. 

CHECK macro instruction. 

Always zero for BDAM. 

WRITE 

Key segment with WRITE. 

ID argument with WRITE. 

Reserved bit. 

Add type of WRITE. 

Unblocked spanned records, with BFTEK=R 

specified and no dynamic buffering: The user's 

program has provided a segment work area pool 

and stored the address of the segment work area 

control block in DCBDYNB. 
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Offset 



52(34) 



Bytes and 


Field 






Alignment 


Name 


Description 


1 


DCBOPTCD 


Option 
Code 


codes: 




1 

.1 


W 


Writc-validity check. 
Track overflow. 




..1 


E 


Extended search. 




...1 .... 


F 


Feedback. 




1... 

].. 

1. 


A 


Actual addressing. 
Dynamic buffering. 
Read exclusive. 




1 


R 


Relative block addressing 



56(38) 4 
62(3E) ..2 
81(51) .3 



DCBSYNAD Address of SYNAD (synchronous error) routine. 

DCBBLKSI Maximum block size. 

DCBLIMCT Number of tracks or number of relative blocks to be 

searched (extended search option). 
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APPENDIX G: EVENT CONTROL BLOCK 



The event control block is used for communications between the various components of 
the system and between problem programs and the system. An event control block is the 
subject of WAIT and POST macro instructions. The following illustration shows the 
format of the event control block; a description of its fields follows the illustration. 



+0 +1 +3 

wlcl I 



0111 


MM 


0100 


0001 


0100 


0010 



Bytes and Hex. 

Offset Alignment Code Bit Dig. Description 

I IOxx xxxx 80 W — Waiting for completion of an event. 

01 xx xxxx 40 C — The event has completed. 

One of the following completion codes will 
appear at the completion of a channel program: 

Access Methods Other Than BTAM 

7F Channel program has terminated without error. 

(CSW contents useful.) 

41 Channel program has terminated with 
permanent error. (CSW contents useful.) 

42 Channel program has terminated because a 
direct access extent address has been violated. 
(CSW contents do not apply.) 

0100 0011 43 I/O ABEND condition occurred while loading 

the error recovery routine. (CSW contents do 
not apply.) 

0100 0100 44 Channel program has been intercepted because 

of permanent error associated with device end 
for previous request. You may reissue the 
intercepted request. (CSW contents do not 
apply.) 

0100 1000 48 Request element for channel program has been 

made available after it has been purged. (CSW 
contents do no apply.) 

0100 1011 4B One of the following errors occurred during tape 

error recovery processing. 

• The CSW command address in the IOB was 
zeros. 

• An unexpected load point was encountered. 
(CSW contents do not apply in either case.) 

0100 MM 4F Error recovery routines have been entered 
because of direct access error but are unable to 
read home addresses or record 0. (CSW contents 
do not apply.) 

0101 0000 50 Channel program terminated with error. Input 
block was a DOS-embedded checkpoint record. 
(CSW contents do not apply.) 
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APPENDIX H: PDABD SYMBOLIC FIELD NAMES 



The following describes PDABD fields of the dummy control section generated by the 
PDABD macro instruction. Included are the names, attributes, and descriptions of the 
dummy control section. The use of any of the symbolic names provided by the dummy 
section should be preceded by a USING instruction specifying IHAPDAB and a dummy 
section base register containing the address of the actual parallel data access block. 



number of DCB addresses in list 
maximum number of addresses allowed 
address of parallel GET routine 
DCB address increment 
address of last DCB entry 
address of DCB entry last processed 
index to ECB list 
start of DCB list 





PDABD 




IHAPDAB 


DSECT 




PDANODCB 


DS 


H 


PDAMAXCB 


DS 


H 


PDAGRTNA 


DS 


A 


PDADCBAI 


DS 


F 


PDADCBLA 


DS 


A 


PDADCBEP 


DS 


A 


PDAECBIX 


DS 


F 


PDADCBAL 


EQU 


* 
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INDEX 



A-type address constant defined 17 
ABEND exit, DCB macro 

BDAM 48 

BISAM 54 

BPAM 60 

BSAM 75 

list format 201-202 

QISAM 84 

QSAM 102 
absexp defined 17 
absolute expression defined 17 
access methods 

general description 
BDAM 44 
BISAM 52 
BPAM 57 
BSAM 64 
QISAM 81 
QSAM 90 

macro instructions used with 175 
ACSMETH operand, SYNADAF macro 170 
actual device addressing 

BDAM 44,50 

QISAM 84 
adding data to a data set 

BDAM 49,182 

BISAM 54,179 

BPAM 181 

BSAM 181,182 

QISAM 116 

QSAM 117 
address constant, A-type 

defined 17 
address feedback 

current block position 139 

next block position 140 
address of buffers 

obtained from a pool 120 

returned to a pool 1 14 
addressing, types of (BDAM) 44,50 
aids, coding 13-15 
alias names in a directory 166-167 
alignment of buffers 

BDAM 45 

BISAM 53 

BPAM 58 

BSAM 66 

QISAM 82 

QSAM 92 
American National Standards Institute 
(ANSI) control characters 

BPAM 62 

BSAM 79 

defined 204 

QSAM 105 
ANSI 

(see American National Standards Institute) 
argument, search 

BDAM 49 

QISAM 86 
ASCII data sets 



block prefix 

BSAM 68 

QSAM 95 

restriction 68,95 
block size 

BSAM 67 

QSAM 93 
buffer length 

BSAM 68 

QSAM 94 
on paper tape 

BSAM 71 

QSAM 97 
restriction on record format 

BSAM 79 

QSAM 106 
ASCII translation routines 
Check routine 30 
DCB option 

BSAM 76 

QSAM 101 
Get routine 117 
Put routine 136 
Write routine 181 
XLATE macro instruction 187 
associated data sets 
closing 36 
opening 123 
specifying 

BSAM 73,74 

QSAM 99,100 
ATTACH macro, relationship with BLDL macro 21 
automatic buffer pool construction 
BDAM 44 
BISAM 52 
BPAM 57 
BSAM 64 
QISAM 82,83 
QSAM 90 
automatic checkpoint restart 31 
automatic volume switching (FEOV macro) 1 1 1 



B 



backspacing 

BSP macro 23 

CNTRL macro 41 
backward read 

open option 124 

read operation 144 
base registers for 

dummy sections 108 

macro instructions 18 
BCD 8-track paper tape code 

BSAM 71 

QSAM 97 
BDAM (basic direct access method) 

general description 44 

macro instructions used with 197 

symbolic field names in DCB 215-217 



Index 223 



BFALN operand (DCB macro) 
BDAM 45 
BISAM 53 
BPAM 58 
BSAM 66 
QISAM 82 
QSAM 92 
BFTEK operand (DCB macro) 
BDAM 45-46 
BSAM 66-67 
QSAM 92-93 
BISAM (basic indexed sequential access method) 
general description 52 
macro instructions used with 197 
symbolic field names in DCB 212-215 
BLDL macro instruction 
description 21-22 
reason codes 22 
return codes 22 
use by access method 197 
used with FIND 112 
BLKSIZE operand (DCB macro) 
BDAM 46 
BPAM 58-59 
BSAM 67 
QISAM 82-83 
QSAM 93-94 
block 

backspacing by 23 
count exit 

BSAM 75 

list format 201 

QSAM 102 
data control 44-107 
data event control 1 89 
descriptor word, relationship with 

BLKSIZE operand 59,67,83,93 

BUFOFF operand 68-69,95 

LRECL operand 85 
event control 189,219 
position feedback 131,178 
positioning with POINT 131-132 
prefix 

(see also BUFOFF operand) 

effect on block length 67 

effect on buffer length 68,93 

effect on data alignment 66,92 
reading 139-145 
size 

(see BLKSIZE operand) 
writing 177-183 
block size for SYSOUT data sets 
(see also BLKSIZE operand) 
BSAM 67 
QSAM 93 
blocking 

data checks (UCS printer) 1 57 
records 

BDAM 44,51 

BPAM 57,62 

BSAM 64,79 

QISAM 81,88 

QSAM 90,105-106 
boundary alignment 
(see BFALN operand) 



BPAM (basic partitioned access method) 
general description 57 
macro instructions used with 197 
symbolic field names for DCB 212-215 
BSAM (basic sequential access method) 
general description 64 
macro instructions used with 197 
symbolic field names for DCB 206-208 
BSP macro instruction 
description 23 
reason codes 23 
return codes 23 
use by access method 197 
BUFCB operand (DCB macro) 
BDAM 46 
BISAM 53 
BPAM 68 
BSAM 68 
QISAM 83 
QSAM 94 
relationship to 

GETBUF macro 120 

GETPOOL macro 121 
buffer 

alignment 

(see BFALN operand) 
control 

dynamic 114 

using FREEBUF macro 1 1 3 

using FREEDBUF macro 114 

using FREEPOOL macro 115 

using GETBUF macro 120 

using GETPOOL macro 121 

using RELSE macro 150 
forms control 

using SETPRT macro 153 
length 

(see also BUFL operand) 

BUILD macro 24 

BUILDRCD macro 26 

for card image mode 68,94 

for ASCII data sets 68,94 

GETPOOL macro 121 
message format (SYNADAF macro) 171-172 
pool construction 

(see also BUFCB operand) 

automatic 

(see BUFNO operand) 

using BUILD macro 24-25 

using BUILDRCD macro 26-27 

using GETPOOL macro 121 
releasing of 

using FREEBUF macro 113 

using FREEDBUF macro 114 

using FREEPOOL macro 115 

using RELSE macro 150 

using SYNADRLS macro 173 
specifying number (see BUFNO operand) 
buffering, types of 
dynamic 1 14 
exchange 93 
problem program controlled 

BDAM 44 

BISAM 52 

BPAM 57 

BSAM 64 
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buffering, types of (continued) 
simple 92-93 
specifying 46,66-67,92-93 
variable-length spanned record 

BDAM 46 

BSAM 67 

QSAM 93 

using BUILDRCD macro 26-27 
BUFL operand (DCB macro) 
BDAM 46-47 
BISAM 53 
BPAM 59 
BSAM 68 
QISAM 83 
QSAM 94 
BUFNO operand (DCB macro) 
BDAM 47 
BISAM 54 
BPAM 59 
BSAM 68 
QISAM 83-84 
QSAM 94 

relationship to CNTRL macro 41 
relationship to NCP operand 55 
BUFOFF operand (DCB macro) 
BSAM 68-69 
QSAM 95 

relationship with READ macro 146 
BUILD macro instruction 
description 24-25 
relationship to 

BFALN operand 45 

BUFCB operand 46 

BUFL operand 47 

BUFNO operand 47 
use by access method 197 
BUILDRCD macro instruction 
description 

execute form 29 

list form 28 

standard form 24-25 
relationship to 

BUFL operand 94 

BUFNO operand 91 

GET macro 118 

PUT macro 137 

TRUNC macro 174 
use by access method 197 
Burroughs 7-track paper tape code 
BSAM 71 
QSAM 97 
BURST operand (SETPRT macro) 

(VS2.03.810) 154,161,164 



CANCEL operand, CHKPT macro 32 
capacity record (R0) 
relationship with 
READ macro 140 
WRITE macro 177,182,183 
card 
code 

BSAM 72 
QSAM 98 
image mode 

buffer length required 68,94 
defined 72,98 
punch 72,98 
reader 73,99 
carriage 

control channel 

CNTRL macro 41-43 
PRTOV macro 133-134 
control characters 
ANSI 182 

CNTRL macro 41-43 
machine 203-204 
PRTOV macro 133-134 
chained scheduling option 
BPAM 62 
BSAM 78 
QSAM 104 
changing partitioned data set member name 1 66- 1 67 
channel 

carriage control 

(see carriage control channel) 
overflow 133-134 
programs, number of 
BISAM 55 
BPAM 60 
BSAM 77 
character arrangement table 78,104 

specifying use of 1 54- 1 55 
CHARS operand (SETPRT macro) 154 
CHECK macro instruction 
description 30 
relationship to 

end of data (EODAD) 60,75 
MACRF operand 49 
number of read and write 
operations (NCP) 55,61,77 
POINT macro 132 
READ macro 139,142,144,146 
WRITE macro 177,179,181,182 
return of exception codes 189-195 
use by access method 197 
checking, write-validity 
BDAM 50 
BPAM 62 
BSAM 78 
QISAM 88 
QSAM 105 
checkpoint data set 3 1 
checkpoint records, embedded (DOS) 
CNTRL macro 41 
POINT macro 131 
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CHKPT macro instruction 
execute form 35 
list form 34 
return codes 33 
standard form 31-33 
use by access method 197 
CLOSE macro instruction 
execute form 40 
list form 39 
relationship to 

BUILDRCD macro 27 

FREEPOOL macro 115 

POINT macro 131 

PUT macro 136,137 

SETL macro 151 
standard form 36-38 
TYPE=T(BSAM) 37 
use by access method 197 
CNTRL macro instruction 
description 41-43 
restriction on use 41 
specified in MACRF operand (DCB macro) 

BSAM 76 

QSAM 103 
use by access method 197 
code 
card 

BSAM 72 

QSAM 98 
completion 

(see code, return) 
control character 

(see control characters) 
conversion 

ASCII to EBCDIC 30,117,187 

EBCDIC to ASCII 181,187 

paper tape 71,97 

XL ATE macro 187 
exception 189-195 
return 

BLDL macro 22 

BSP macro 23 

CHKPT macro 33 

FIND macro 112 

RELEX macro 149 

SETPRT macro 158-160 

STOW macro 167-168 

S YN AD AF macro 171 

SYNADRLS macro 173 

WRITE macro 184 
CODE suboperand (DCB macro) 
BSAM 71 
QSAM 97 
coding 

aids 13-15 

macro instructions 16-18 
registers as operands 18 
column, binary 

(see card image mode) 
eliminate mode, read 

BSAM 72,73 

QSAM 98,99 



completion codes 
BLDL macro 22 
BSP macro 23 
CHKPT macro 33 
FIND macro 112 
RELEX macro 149 
SETPRT macro 158-160 
STOW macro 167-168 
SYNADAF macro 171 
SYNADRLS macro 173 
WRITE macro 184 
completion testing of I/O operations 30,175 
concatenation 

input data sets (BPAM) 57 
condition, exception 189-194 
construct 

a buffer pool 

(see buffer pool construction) 
a data control block 

(see DCB macro instruction) 
a DECB (data event control block) 1 89 
contents of registers on entry to 
exit list 201 
SYNAD 194-195 
control 

characters 203-204 
I/O device 41-43,133 
page format 133-134 
printer (3800) 153-157 
releasing 

buffer (FREEBUF macro) 113 
buffer pool (FREEPOOL macro) 1 1 5 
data block (RELEX macro) 149 
dynamically acquired buffer 114,178 
QSAM buffer (RELSE macro) 150 
requesting 

buffer (GETBUF macro) 120 
buffer pool (GETPOOL macro) 112-113 
data block 121 
control block39, 142-146 
buffer pool 

(see BUFCB operand) 
data 

(see DCB macro instruction) 
data event 1 89 
event 219 
control characters 
ANSI 204 

CNTRL macro 41-43 
machine 203-204 
PRTOV macro 133-134 
specifying for 
BPAM 62 
BSAM 79 
QSAM 105,106 
control section (CSECT) 

(see DCB macro instruction) 
COPIES operand (SETPRT macro) 155 

modifying 1 57 
copy modification module, specifying 156 
COPYNR operand (SETPRT macro) 1 5 5 

modifying 1 57 
count exit, block 
BSAM 75 
format list 201 
QSAM 102 
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cylinder 

index 87 

overflow area 84 
CYLOFL operand 84 

D 

D-format records 

BSAM 79 

QSAM 106 
data, end of 

(see EODAD operand) 
data block 

exclusive control of 139 

locating with POINT macro 131-132 

release of exclusive control 149 

retrieving 116-119,139-146 

writing 135-138,177-183 
data checks 

blocking and unblocking 78,105,157 

restriction with CNTRL macro 41-43 
data control block 

completing 123 

construction 

(see DCB macro instruction) 

DCBBLKCT field 42 

DCBEXCD1 field 189 

DCBEXCD2 field 189 

DCBLRECL field 136 

DCBNCRHI field 56 

DCBOFLGS field 126 

description 

(see DCB macro instruction) 

dummy section for 108-109 

exit list 

(see EXLST operand) 

special options with BLDL macro 21-22 

symbolic references to 205-217 
data definition statement 

(see DD statement) 
data event control block 

construction 147,185 

description 189 

exception code 189-195 

modifying with execute form 1 48 , 1 86 

requirement with CHECK macro 30 

requirement with FREEDBUF macro 1 1 4 
data management parameter list 39, 1 27 
data mode 

GET macro 103,118 

PUT macro 103,137 
data protection image (DPI) 

BSAM 73,74 

QSAM 99,100 



data set 

block size for SYSOUT 67,93 

closing 36-38 

connecting to 123-126 

disconnecting from 36-38 

disposition at close 37 

opening 123-126 

organization 

(see DSORG operand) 

temporary closing 37-38 

types 

(see access methods) 
data translation 

(see code conversion) 
data transmittal modes 

data 103,118,137 

locate 116,118,135,136-137 

move 116,118,135,137 

specified in DCB 86,103 

substitute 118,137 
DCB ABEND exit 

BDAM 48 

BISAM 54 

BPAM 60 

BSAM 75 

list format 201-202 

QISAM 85 

QSAM 102 
DCB macro instruction 

BDAM 44-51 

BISAM 52-56 

BPAM 57-63 

BSAM 64-80 

QISAM 81-89 

QSAM 90-107 

use by access method 197 
DCB open exit routine 

relationship to OPTCD operand 50,79 

restriction with BUILDRCD macro 26 
DCB operands 

description 

(see DCB macro instruction) 

symbolic names for 205-217 
DCBD macro instruction 

description 108-109 

use by access method 197 
DD statement, relationship to 

data control block 

(see DDNAME operand) 

NOTE macro 122 

OPEN macro 123-125 

POINT macro 131 
DDNAME operand (DCB macro) 

BDAM 47 

BISAM 54 

BPAM 59-60 

BSAM 69 

QISAM 84 

QSAM 95 
DEB validity checking 123 
deblocking records 

BDAM 44,51 

BPAM 57,62 

BSAM 64,79 

QISAM 81,88 

QSAM 90,106 
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DECB 

(see data event control block) 
deferred checkpoint restart 31 
delete option 

description 87 
DEN suboperand (DCB macro) 

BSAM 70 

QSAM 96 
density, recording 

(see DEN operand) 
descriptor word 

block 

BPAM 59 
BSAM 67,68-69,146 
QISAM 83,85 
QSAM 93,95 

record 

BSAM 68-69,76 
QISAM 83,85 
QSAM 102 

segment 67,146 
DEVD operand (DCB macro) 

BSAM 69-75 

DCBD macro 109 

QSAM 95-101 
device addressing, types of (BDAM) 50 
device capacities 199-200 
device types in a dummy section 109 
direct-access storage device 

capacity 199-200 

considerations with 
BSP macro 23 
CHKPT macro 31 
CLOSE macro 36,37 
POINT macro 131-132 

interface in DCB 208 
direct data set 

(see BDAM) 
direct search option 

BSAM 78 

QSAM 105 
directory, partitioned data set 

creation 57 

obtaining contents with BLDL 21-26 

operations performed by STOW macro 166-167 

search by FIND macro 112 
DISP option 

(see disposition option) 
disposition option 

CLOSE macro 37 

OPEN macro 125 

requirement for extending an 
ISAM data set 122 
DOS embedded checkpoint records, relationship with 

CNTRL macro 41 

POINT macro 131 

DOS/OS interchange feature, specifying 79,105 
doubleword alignment 

(see BFALN operand) 
DPI (data protection image), specifying 

for BSAM 73,74 

for QSAM 99,100 
DSECT for 

DCB symbolic names 205 



DSORG operand 
CHECK macro 30 
DCB macro 

BDAM 47-48 
BISAM 54 
BPAM 60 
BSAM 75 
QISAM 84 
QSAM 101 
dummy control section 
DCBD macro 108-109 
how used 205 
PDABD macro 130 
dummy data block (BDAM) 1 82-1 83 
dummy key 182 
dynamic buffering 

effect on buffer length 46-47,53 
effect on number of channel programs 55 
requesting in READ macro 140,142 
requesting in WRITE macro 178,179 
returning buffer to the pool 114,178 
specified in BDAM DCB 49 
specified in BISAM DCB 55 



E 



EBCDIC 

(see extended binary coded decimal 

interchange code) 
ECB 

(see also event control block) 

operand, WAIT macro 175 
ECBLIST operand, WAIT macro 175 
eliminate mode, read column 

BSAM 72,73 

QSAM 98,99 
embedded checkpoint records (DOS) 

CNTRL macro 41 

POINT macro 131 
end of data 

(see EODAD operand) 
end of file on magnetic tape, ignoring 

BSAM 79 

QSAM 105 
end of sequential retrieval (ESETL macro) 1 10 
end of volume 

exit 

BSAM 75 
QSAM 102 

forced (FEOV macro) 1 1 1 
entry to 

exit routine 201 

SYN AD routine 189 
EODAD operand (DCB macro) 

BPAM 60 

BSAM 75 

QISAM 84 

QSAM 101 
EODAD routine, relationship to 

BSP macro 23 

CHECK macro 30 

CNTRL macro 41 

FEOV macro 109 

GET macro 116,119 

POINT macro 131 
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EROPT operand (DCB macro) 101-102 
ERP (error recovery procedure for tape) 
BSAM 78 
QSAM 105 
error analysis, I/O 
exception codes 

BDAM 193 

BISAM 190 

QISAM 191 
register contents 

BDAM 195 

BISAM 195 

BPAM 195 

BSAM 195 

QISAM 194 

QSAM 195 
relationship with 

CHECK macro 30 

CNTRL macro 42-43 

DCB macro 79,105 

GET macro 116,119 

POINT macro 132 

PUT macro 135,137 

PUTX macro 138 

SETL macro 152 

SYNADAF macro 169 
specifying in DCB macro 

BDAM 51 

BISAM 56 

BPAM 63 

BSAM 80 

QISAM 89 

QSAM 106 
status indicators 

BDAM 196 

BPAM 196 

BSAM 196 

QISAM 189 

QSAM 196 
error codes 

(see return codes) 
error conditions while opening a data set 125-126 
error exits 

CHECK macro 30 
CNTRL macro 42-43 
DCB macro 78,105 
GET macro 116,119 
POINT macro 132 
PUT macro 135,137 
PUTX macro 138 
SETL macro 152 
SYNADAF macro 169-170 
error option operand (QSAM) 101 
error recovery procedure for tape 78, 105 
ESETL macro instruction 
description 110 
relationship to 

GET macro 116 

SETL macro 151 
use by access method 197 
event control block 1 89,2 1 9 
exception code 189-194 



exchange buffering 

buffer alignment for 92 
restrictions 

for VS2 systems 93 

record format 93 

track-overflow feature 93,106 
specified in DCB 93 
exclusive control of data block (BDAM) 
releasing of 178 
requesting of 139 
specified in DCB 50 
EXCP macro, relationship with SYNADAF macro 169 
EXCP programming, restriction 153 
execute form instructions 
BUILDRCD macro 29 
CHKPT macro 35 
CLOSE macro 40 
OPEN macro 128 
READ macro 148 
SETPRT macro 163-165 
WRITE macro 186 
exit 

(see also EXLST operand) 
block count 75,102 
data control block 

{see EXLST operand) 
end of data 

(see EODAD operand) 
end of volume 75,102 
error analysis 

(see error exits 
FCB image 75,102 
list format 201 

open (see DCB open exit routine) 
user labeling 75,102 
user totaling 75,102 
EXLST operand (DCB macro) 
BDAM 48 
BISAM 54 
BPAM 60 
BSAM 75 
list format 201 
QISAM 85 
QSAM 102 
expression 

absolute (absexp) 17 
relocatable (relexp) 17 
EXTEND open option (VS2.03.808) 124 
extended binary coded decimalinterchange code (EBCDIC) 
ASCII translation 

Check routine 30 

DCB option 78,104 

GET routine 117 

Put routine 136 

Write routine 181 

XLATE macro 187 
paper tape translation 

BSAM 71 

QSAM 97 
extended search option 
LIMCT operand 48-49 
OPTCD operand 50 
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F-format records 

(see RECFM operand) 
FCB 

image, defining 75,102 

operand (SETPRT macro) 155 
feedback 

block position 139,178 

next address 140 
FEOV macro instruction 111 

use by access method 197 
file, end of 

{see end of file) 
FIND macro instruction 

description 112 

reason codes 1 12 

return codes 1 12 

use by access method 197 
fixed-length records 

(see BLKSIZE operand; RECFM operand) 
FLASH operand (SETPRT macro) 156 

modifying 157 
format 

exit list 201 

page 133 

record 

BDAM 51 
BPAM 62 
BSAM 79-80 
QISAM 88 
QSAM 105-106 
forms alignment, specifying 155 
forms control buffer (FCB) 

image, defining 75,102 

operand (SETPRT macro) 155 
forms overlay frame, specifying 155 
forward space (CNTRL macro) 42 
FREE option with CLOSE macro 37 
FREEBUF macro instruction 

description 113 

relationship to 

BUILD macro 24 
GETBUF macro 120 

use by access method 197 
FREEDBUF macro instruction 

description 114 

use by access method 197 

used with BISAM 54,179 
FREEPOOL macro instruction 

description 115 

relationship to 

CLOSE macro 36 
GETPOOL macro 121 

use by access method 197 
Friden 8-track paper tape code 

BSAM 71 

QSAM 97 
full-track-index write operation 88 
fullword boundary alignment 

(see BFALN operand) 
FUNC suboperand (DCB macro) 

BSAM 72-73,74 

QSAM 98-99,100 



GET macro instruction 
ASCII translation 117 
data mode (QSAM) 103,118 
for 

QISAM 116 

QSAM 117-119 
locate mode 

QISAM 86,116 

QSAM 103,118 
move mode 

QISAM 86,116 

QSAM 103,118 

restriction when using CNTRL macro 41 , 103 
relationship to 

CNTRL macro 41 

EODAD 

(see EODAD operand) 

PDAB macro 129 

RELSE macro 150 

SETL macro 151 
specified in DCB macro 

QISAM 86 

QSAM 103 
substitute mode (QSAM) 103,118 
TYPE=P 118 
use by access method 197 
Get routine exits 116,119 
GETBUF macro instruction 
description 120 
relationship to 

BUILD macro 24 

FREEBUF macro 113 
use by access method 197 
GETPOOL macro instruction 
description 121 
relationship to 

BFALN operand 45 

BUFCB operand 46 

BUFL operand 47 

BUFNO operand 47 

FREEPOOL macro 115 
use by access method 197 



IBM BCD perforated tape 

BSAM 71 

QSAM 97 
IHADCB dummy section 108 
IHAPDAB dummy section 130 
image 

FCB (forms control buffer) 75,102,155 

UCS (universal character set) 153,157 
image, data protection 

BSAM 73,74 

QSAM 99,100 
image mode, card 

BSAM 72 

QSAM 98 
independent overflow area, specifying 87 
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index 

cylinder 87 
highest level 
address of 55 
size of 56 
master 

number of tracks per level 87 
specified in OPTCD operand (DCB macro) 
space allocation for 81 
indicators, status 196 
INIT operand (SETPRT macro) 1 56 
INOUT option (OPEN macro) 124 
input data sets 
closing 37-39 
opening 123-126 
READ or GET specified in DCB 
BDAM 49 
54 
61 
76 
86 
103 



87 



BISAM 
BPAM 
BSAM 
QISAM 
QSAM 
reading 
BDAM 
BISAM 
BPAM 



139-141 
142-143 
144-145 

BSAM (read a direct data set) 146 
BSAM (read a sequential data set) 144-145 
QISAM 116 
QSAM 117-119 
testing completion of I/O operations 
CHECK 30 
WAIT 175-176 
INPUT option (OPEN macro) 123,124 
input/output devices 

card reader and card punch 41 
control of 

CNTRL macro 41-43 
PRTOV macro 133 
magnetic tape 41 
printer 41 
3505 card reader 

DCB macro 72,73,98,99,100 
3525 card punch 
CLOSE macro 36 
CNTRL macro 41 
DCB macro 72,73,74,98,99,100 
OPEN macro 123 
input/output error analysis 

(see SYNAD routine) 
input/output operation 
completion of 30,176 
status indicators 196 
interface, DCB 

for BPAM 210-211 

for BSAM 210-211 

for card reader, card punch 209 

for direct-access devices 208 

for magnetic tape 208 

for paper tape 209 

for printer 210 

for QSAM 211 



interface, logical record 

invoked by BUILDRCD macro 26 

provided by QSAM 90,93 

specifying in DCB macro (BFTEK) 92-93 

used with GET macro 117 

used with PUT macro 136 
ISAM 

general description 52,81 

macro instructions used with 197 

symbolic field names in DCB 212-215 



JFCBE exit 

exit list format 201 
EXLST operand 102 
relationship with OPTCD parameter 79 
job control language (JCL) 

LABEL parameter to request ASCII 

translation 30,117,136 

DD statement, relationship to 

CHKPT macro 31 

CLOSE macro 36 

data control block 

(see DDNAME operand) 
DCB macro 47,60-61 
GET macro 117 
NOTE macro 122 
OPEN macro 123-124 
POINT macro 131 
PUT macro 135 
job step checkpoint restart 3 1 

K 

key (BDAM) 

address 140 

reading 139 

specifying as search argument 49 

specifying length 48 

writing 178 
key (ISAM) 

address 143,180 

reading 142 

specifying length 85 

specifying position 88 

writing 179 
key length 

(see KEYLEN operand) 
key position, relative (RKP) 88-89 
key, record 

PUT macro 135 

READ macro 143 

RKP operand (DCB macro) 88-89 

SETL macro 151-152 

WRITE macro 180 
KEYLEN operand (DCB macro) 

BDAM 48 

BPAM 60-61 

BSAM 75-76 

QISAM 85 



Index 231 



label 

(see also EXLST operand) 
exit list format 201 
input data set 105,111,123 
output data set 

CLOSE macro 36 

FEOV macro 111 

OPEN macro 123 
user, processing 75,102 
LABEL parameter in DD statement 30,117,136 

Leave option 

CLOSE macro 36 
FEOV macro 111 
OPEN macro 125 
length 
buffer 

(see BUFL operand) 
key 

(see KEYLEN operand) 
record 

(see LRECL operand) 
levels of master index (ISAM) 87 
L1MCT operand (DCB macro) 48-49 
line spacing, printer 
CNTRL macro 41-43 
PRTSP suboperand (DCB macro) 
BSAM 71-72 
QSAM 97 
LINK macro, relationship with BLDL macro 21 
list address 

control program 31,35 
data management 40, 1 28, 1 66 
list form instructions 

BUILDRCD macro 28- 
CHKPT macro 34 
CLOSE macro 39 
OPEN macro 127 
READ macro 147 
SETPRT macro 161-162 
WRITE macro 185 
list format, exit 201 

LOAD macro, relationship with BLDL macro 21 
load mode (QISAM) 81 
loading 

forms control buffer (FCB) 155 
universal character set buffer (UCS) 1 57 
locate mode 

BUILDRCD macro 26 
GET macro 
QISAM 116 
QSAM 118 
PUT macro 
QISAM 135 
QSAM 136 
specified in DCB macro 
QISAM 86 
QSAM 103 
logical record interface (see interface, logical record) 
logical record length for 

(see also LRECL operand) 
GET macro 117 
PUT macro 135,136 
PUTX macro 138 



LONG operand, WAIT macro 175 
lower limit of sequential retrieval 
(SETL macro) 151-152 
LRECL operand (DCB macro) 

BPAM 61 

BSAM 76 

QISAM 85 

QSAM 102 

M 

machine control characters 
BPAM 62 
BSAM 79 
description 203-204 
QSAM 105-106 
MACRF operand (DCB macro) 
BDAM 49-50 
BISAM 54-55 
BPAM 61 
BSAM 77 
QISAM 86 
QSAM 103 
macros, data management 
BLDL 21-22 
BSP 23 
BUILD 24-25 
BUILDRCD 

execute form 29 
list form 28 
standard form 26-27 
CHECK 30 
CHKPT 

execute form 35 
list form 34 
standard form 31-33 
CLOSE 

execute form 40 
list form 39 
standard form 36-38 
CNTRL 41-43 
DCB for 

44-51 
52-56 
57-63 
64-80 
81-89 
90-107 
108-109 
110 



BDAM 

BISAM 

BPAM 

BSAM 

QISAM 

QSAM 
DCBD 
ESETL 
FEOV 111 
FIND 112 
FREEBUF 113 
FREEDBUF 114 
FREEPOOL 115 
GET for 

QISAM 116 

QSAM 117-119 
GETBUF 120 
GETPOOL 121 
NOTE 122 
OPEN 

execute form 128 

list form 127 

standard form 123-126 



232 OS/VS2 Data Management Macro Instructions 



Page of GC26-3873-0 

As Updated March 30, 1979 

By TNL GN26-0941 



macros, data management (continued) 
READ for 

BDAM 139-141,146 

BISAM 142-143 

BPAM 144-145 

BSAM 144-146 

execute form 148 

list form 147 
RELEX 149 
RELSE 150 
SETL 151-152 
SETPRT 

execute form 163-165 

list form 161-162 

standard form 153-160 
STOW 166-168 
SYNADAF 169-172 
SYNADRLS 173 
TRUNC 174 
WAIT 175-176 
WRITE for 

BDAM 177-178,182-184 

BISAM 179-180 

BPAM 181 

BSAM 181 

execute form 186 

list form 185 
XL ATE 187 
macro instruction coding 13-15 
macro use by access method 197 
magnetic tape 
backspace 

BSP macro 23 

CNTRL macro 41 
considerations with 

BSP macro 23 

CHKPT macro 31 

CLOSE macro 36-38 

CNTRL macro 58 

POINT macro 131-132 
density 70,96 
end-of-file, ignored 79,105 
final volume positioning (FEOV macro) 111 
forward space 41 
interface in DCB 208 
read backward 144 
recording technique 70,96 
restriction when using NOTE macro 122 
restriction when using POINT macro 131 
short error recovery procedure 78, 105 
Mass Storage System (see MSS) 
master index 

highest level in storage 

address of storage area 55 

size of storage area 56 
number of tracks per level 87 
option specified in DCB 87 
MAXDCB operand, PDAB macro 129 
member, partitioned data set 

complete a list with BLDL macro 21-22 
locate beginning with FIND macro 1 12 
update directory with STOW macro 166-167 



MF operand 

BUILDRCD macro 28,29 
CHKPT macro 34,35 
CLOSE macro 40 
OPEN macro 127,128 
READ macro 147,148 
SETPRT macro 162,165 
WRITE macro 185,186 
mode 

(see also MACRF operand) 
card image 

BSAM 72 

QSAM 98 
data(QSAM) 103,118,137 
load(QISAM) 81 
locate 

QISAM 86,116,135 

QSAM 103,118,136 
move 

QISAM 86,116,135 

QSAM 103,118,137 
optical mark read 

BSAM 73 

QSAM 99 
read column eliminate 

BSAM 72,73 

QSAM 98,99 
resume load mode 81 
scan (QISAM) 81,86 
substitute (QSAM) 103,118,137 
MODE suboperand (DCB macro) 
BSAM 72,73 
QSAM 98,99 
MODIFY operand (SETPRT macro) 1 56 
modifying a parameter list 
BUILDRCD macro 29 
CHKPT macro 34 
CLOSE macro 40 
OPEN macro 127,128 
READ macro 148 
SETPRT macro 163 
WRITE macro 186 
move mode 
QISAM 

GET macro 116 

PUT macro 135 

specified in DCB 86 
QSAM 

GET macro 118 

PUT macro 137 

specified in DCB 103 
restriction 41,103 
MSHI operand (DCB macro) 55 
MSS (Mass Storage System) 
andOPTCD=U 78,105 
device capacity 200 
in DCB 208,210,211,212,215 
MSWA operand (DCB macro) 55 
multiline print option 
BSAM 73,74 
QSAM 99,100 
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N 

National Cash Register 8-track paper tape code 

BSAM 71 

QSAM 97 
NCP operand (DCB macro) 

BISAM 55 

BPAM 61 

BSAM 77 
next address feedback 

BDAM (creating) 183 

BDAM (existing) 140 
nonsequential processing of sequential data 64 
NOTE macro instruction 

description 122 

relationship with POINT macro 122 

restriction when using BSP macro 23 

specified in DCB 
BPAM 61 
BSAM 76 

use by access method 197 
NTM operand (DCB macro) 87 
number of channel programs 

(see NCP operand) 
number of tracks per index level 

(see NTM operand) 

o 

online printer 
control 41-43 
skipping 133,203-204 
spacing 133,203-204 
open exit (see DCB open exit routine) 
OPEN macro instruction 
execute form 128 
list form 127 
relationship to 

CLOSE macro 36 

DDNAME operand (see DDNAME operand) 
FEOV macro 111 
GETPOOL macro 121 
NOTE macro 122 
POINT macro 131 
READ macro 144 
WRITE macro 181 
standard form 123-126 
use by access method 197 
open operation, testing 125-126 
open options 123-125 
operand, substitution for 16 
OPTCD operand 
DCB macro 
BDAM 50 
BPAM 62 
BSAM 77-78 
QISAM 87 
QSAM 104-105 
SETPRT macro 157 
optical mark read mode 
BSAM 73 
QSAM 99 
option codes 

(see OPTCD operand) 
organization, data set 
(see access methods) 



OUTIN open option 124 
OUTINX open option (VS2.03.808) 124 
output data sets 
closing 36-38 
opening 123-126 

WRITE or PUT specified in DCB macro 
BDAM 50 
BISAM 55 
BPAM 61 
BSAM 77 
QISAM 86 
103 



QSAM 

writing 
BDAM 
BISAM 
BPAM 
BSAM 



177-178 
179-180 
181 
181 

BSAM (write to a direct data set) 1 82-1 83 
QISAM 135,138 
QSAM 136-137 
OUTPUT open option 124 
overflow 

area, independent 87 
channel 133 

exit address (PRTO V macro) 1 33 
printer carriage 133 
overflow feature, track 
BDAM 51 
BPAM 62 
BSAM 80 
QSAM 106 
restrictions 

chained scheduling 62,106 
exchange buffering 93,106 
ISAM 81 

with OPTCD operand 78,105 
overlay frame, specifying 155 
overprinting 133 



paper tape codes 

BSAM 71 

QSAM 97 
parallel data access block (PDAB) 

constructing 129 

generating a DSECT 130 

symbolic field names 221 
parameter list construction 

BUILDRCD macro 28 

CHKPT macro 34 

CLOSE macro 39 

OPEN macro 127 

READ macro 147 

SETPRT macro 161-162 

WRITE macro 185 
parameter list, modification 

BUILDRCD macro 29 

CHKPT macro 35 

CLOSE macro 40 

OPEN macro 128 

READ macro 148 

SETPRT macro 163-165 

WRITE macro 186 
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parameter list, modification 

BUILDRCD macro 29 

CHKPT macro 35 

CLOSE macro 40 

OPEN macro 128 

READ macro 148 

SETPRT macro 163-165 

WRITE macro 186 
partitioned data set 

general description 57 

macro instructions used with 197 

relationship to 

BLDL macro 21-22 
FIND macro 112 
STOW macro 166-167 
PDAB macro instruction 129 

use by access method 197 
PDABD 

macro instruction 130 

symbolic field names 221 

use by access method 197 
POINT macro instruction 

description 131-132 

relationship to 
BSAM 64 
NOTE macro 122 

restriction 

with BSP macro 23 

specified in MACRF operand 
BPAM 61 
BSAM 76,77 

use by access method 197 
position, relative key (RKP) 88 
position feedback 

current block 139,178 

next block 140,183 
positioning volumes 

using CHECK macro 30 

using CLOSE macro 36-38 

using FEOV macro 1 1 1 

using OPEN macro 123-126 

using POINT macro 131-132 
prefix, block 

(see also BUFOFF operand) 

effect on block length 67,93 
effect on buffer length 68,93 
effect on data alignment 66,92 
print option for 3525 

BSAM 73,74 

QSAM 98,100 
printer 

carriage control 41-43,133-134 

character set buffer loading 157 

control characters 203-204 

control information 153 

control tape 133-134 

forms control buffer loading 155 

skipping 41-43,203-204 

spacing 41-43,203-204 
program, channel 

BISAM 55 

BPAM 61 

BSAM 77 
protection option, data 

BSAM 73,74 

QSAM 99,100 



PRTOV macro instruction 133-134 

use by access method 197 
PRTSP suboperand (DCB macro) 
BSAM 71-72 
QSAM 97 
punch, card 72,98 
PUT macro instruction 

data mode (QSAM) 103,137 
for 

QISAM 135 

QSAM 123-125 
locate mode 

QISAM 135 

QSAM 136 
move mode 

QISAM 135 

QSAM 137 
relationship with 

PRTOV macro 133 

SYNADAF macro 169 

TRUNC macro 174 
specified in DCB macro 

QISAM 86 

QSAM 103 
substitute mode (QSAM) 137 
use by access method 197 
PUTX macro instruction 
description 138 
output mode 138 

relationship with TRUNC macro 174 
specified in DCB macro 

QISAM 86 

QSAM 103 
update mode 138 
use by access method 197 



QISAM (queued indexed sequential access method) 

general description 81 

macro instructions used with 197 

symbolic field names in DCB 212-215 
QSAM (queued sequential access method) 

general description 90 

macro instructions used with 197 

symbolic field names in DCB 206-210 
queued access technique 

(see QISAM and QSAM) 

R 

RDBACK open option 124 
read backward, magnetic tape 124, 144 
read column eliminate mode 
BSAM 72,73 
QSAM 98,99 
READ macro instruction 
execute form 1 48 
for 

BDAM 139-141,146 
BISAM 142-143 
BPAM 144-145 
BSAM 144-146 
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READ macro instruction (continued) 
list form 147 
relationship to 

BFTEK operand 46,66 

BUFL operand 47 

CHECK macro 30 

EODAD operand 60,75 

FIND macro 112 

FREEDBUF macro 114 

KEYLEN operand 48 

LIMCT operand 48 

MACRF operand 49,54-55,61,76-77 

NCP operand 55,61,77 

OPTCD operand 50 

POINT macro 131 

RELEX macro 149 

WAIT macro 175 

WRITE macro 177-178 
specified in DCB macro 

BDAM 49 

BISAM 54 

BPAM 61 

BSAM 76 
standard form 

BDAM 139-141 

BISAM 142-143 

BPAM 144-145 

BSAM (read direct data set) 146 

BSAM (read sequential data set) 144-145 
use by access method 197 
reason codes 

BLDL macro 22 
BSP macro 23 
FIND macro 112 
SETPRT macro 160 
STOW macro 167-168 
RECFM operand (DCB macro) 
BDAM 51 
BPAM 62 
BSAM 79-80 
QISAM 88 
QSAM 105-106 
record 
area 

construction 144 

deletion option (ISAM) 87 

format 

(see RECFM operand) 

length 

(see LRECL operand) 
descriptor word, relationship with 

BSAM 68-69,76 

QISAM 83,85 

QSAM 102 
physical 

(see BLKSIZE operand) 
retrieval 116-119,139-146 
segment 136 

variable-length, spanned 26,93 
writing 135-138,177-183 
recording density, magnetic tape 
BSAM 70 
QSAM 96 
recording technique, magnetic tape 
BSAM 70 
QSAM 96 



register 

contents on entry to 

DCB exit routine 201 
overflow exit routine 133 
SYNAD routine 194-195 

DCBDbase 108-109 

usage rules 22 
relative addressing 

BDAM 44,50 

FIND macro 112 

POINT macro 131 
relative key position 88 
release 

buffer 113 

buffer pool 115 

dynamically acquired buffer 1 14 

exclusive control 178 

QSAM buffer 150 
RELEX macro instruction 

description 149 

relationship to MACRF operand 50 

return codes 149 

use by access method 197 
relexp defined 17 
relocatable expression defined 17 
RELSE macro instruction 150 

use by access method 197 
reorganization statistics (ISAM) 81,87 
REREAD option 

CLOSE macro 36 

OPEN macro 125 
restart job from a checkpoint 

automatic 31 

deferred 31 
restore data control block 36-38 
resume load mode 81 
return codes 

BLDL macro 22 

BSP macro 23 

CHKPT macro 33 

FIND macro 112 

RELEX macro 149 

SETPRT macro 158-160 

STOW macro 167-168 

SYNAD AF macro 151 

SYNADRLS macro 173 

WRITE macro 184 
RETURN macro, relationship with SYNAD operand 

BDAM 51 

BISAM 56 

BPAM 63 

BSAM 80 

QISAM 89 

QSAM 106 
REWIND option 

CLOSE macro 36 

FEOV macro 111 
REXMIT operand, SETPRT macro 1 57 
RKP operand (DCB macro) 88-89 

relationship with LRECL operand 85 
R0 (see capacity record) 
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save area 

general register requirements li 

SYNADAF requirement 169 

SYNADRLS macro 173 
scan mode 81,86 
search 

partitioned data set directory 
BLDL macro 21-22 
FIND macro 112 

type of 

BDAM 49 
QISAM 86 
search argument 

BDAM 49 

QISAM 86 
search direct option 78,105 
search option, extended 50 
segment 

buffer 135 

descriptor word 67,147 

interface, restriction 26 

work area 47 
sequential access methods 

(see access methods) 
services, optional 

BDAM 50 

BPAM 62 

BSAM 77-78 

QISAM 87 

QSAM 104 
SETL macro instruction 

description 151-152 

relationship to 

ESETL macro 110 
GET macro 116 

use by access method 197 
SETPRT macro instruction 

execute form 163-165 

list form 161-162 

reason codes for 3800 160 

return codes 158-160 

standard form 153-160 

use by access method 197 
simple buffering 92 
skipping, printer 

(see also spacing, printer) 

CNTRL macro 41-43 

control characters 203-204 
SMSI operand (DCB macro) 56 
SMSW operand (DCB macro) 56 
space, magnetic tape 

backward 23,41 

forward 41 
space allocation, data set 

BPAM 57 

QISAM 81 
spacing, printer 

(see also skipping, printer) 

CNTRL macro 41-43 

control characters 203-204 

specified in DCB macro 
BSAM 71 
QSAM 97 



spanned records (see 

variable-length, spanned records) 
STACK suboperand (DCB macro) 
BSAM 72,74 
QSAM 98,100 
stacker selection 

CNTRL macro 41-43 
control characters 203-204 
specified in DCB macro 

BSAM 72,74 

QSAM 98,100 
standard blocks 

restriction with OPTCD 

operand 78,105 
specifying 79,106 
statistics reorganization (ISAM) 81,87 
status 

following an I/O operation 189-196 
indicators 196 
STOW macro instruction 
description 166-168 
directory action 167 
reason codes 168 
return codes 167-168 
use by access method 197 
substitute mode 
GET macro 118 
PUT macro 137 
specified in DCB macro 103 
switching volumes 
CHECK macro 30 
FEOV macro 111 
symbol defined 16 
SYNAD operand (DCB macro) 
BDAM 51 
BISAM 56 
BPAM 63 
BSAM 80 
QISAM 89 
QSAM 106-107 
SYNAD routine 
exception codes 

BDAM 193 

BISAM 190 

QISAM 191 
register contents 

BDAM 195 

BISAM 195 

BPAM 195 

BSAM 195 

QISAM 194 

QSAM 195 
relationship with 

CHECK macro 30 

CNTRL macro 42-43 

DCB macro (see SYNAD operand) 

GET macro 116,119 

POINT macro 132 

PUT macro 135,137 

PUTX macro 138 

SETL macro 152 

SYNADAF macro 170 
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SYNAD routine (continued) 
specifying in DCB macro 

BDAM 51 

BISAM 56 

BPAM 63 

BSAM 80 

QISAM 89 

QSAM 106-107 
status indicators 

BDAM 196 

BPAM 196 

BSAM 196 

QSAM 196 
SYNADAF macro instruction 
description 169-171 

relationship with SYNADRLS macro 173 
return codes 171 
use by access method 197 
SYNADRLS macro instruction 
description 173 

relationship with SYNADAF macro 169 
return codes 173 
use by access method 197 
synchronizing I/O operations 30,175-176 
synchronous error exit 

{see SYNAD operand) 
SYSIN restrictions 
BSP macro 23 
CNTRL macro 41 
DEVD operand (DCB macro) 

BSAM 69-70 

QSAM 95-96 
FEOV macro 111 
MACRF operand 77 
NOTE macro 122 
OPEN macro 123,124 
OPTCD operand 78,104 
PUTX macro 138 
RECFM operand 80,106 
RELSE macro 150 
SYSOUT restrictions 
BSP macro 23 
CNTRL macro 41 
FEOV macro 111 
MACRF operand 77 
NOTE macro 122 
OPEN macro 123,124 
OPTCD operand 78,104 
POINT macro 131 
PUTX macro 138 



table reference character for 3800 78,104,156 
tape codes, paper 

BSAM 71 

QSAM 97 
tape density, magnetic 

BSAM 70 

QSAM 96 
tape error recovery procedure 

BSAM 78 

QSAM 105 



tape recording technique 

BSAM 70 

QSAM 96 
Teletype 5-track paper tape code 

BSAM 71 

QSAM 97 
temporary close of data set 36-38 
termination, abnormal 

Check routine 30 

end of data 

{see EODAD operand) 

uncorrectable I/O error 
{see SYNAD operand) 
testing completion of I/O 30,175-176 
testing for open data set 125-126 
totaling exit, user 

BSAM 75 

list format 201 

QSAM 102 
track addressing, relative 

BDAM 44,50 

FIND macro 112 

POINT macro 131-132 
track index write, full 88 
track-overflow feature 

BDAM 51 

BPAM 62 

BSAM 80 

QSAM 106 

restrictions 

chained scheduling 62,106 
exchange buffering 96,103 
ISAM 81 

with OPTCD operand 78,105 
translation 

ASCII to EBCDIC 
CHECK macro 30 
GET macro 117 
XLATE macro 187 

EBCDIC to ASCII 
PUT macro 136 
WRITE macro 181 
XLATE macro 187 

paper tape code 7 1 ,97 
transmittal modes 

{see also MACRF operand) 

data 103,118,137 

locate 116,118,135,136 

move 116,118,135,137 

specifying 86,103 

substitute 118,137 
TRTCH suboperand (DCB macro) 

BSAM 70-71 

QSAM 96 
TRUNC macro instruction 

description 174 

specified in QSAM DCB 103 

use by access method 197 
truncating a block 174 
TYPE=P (GET macro) 118 
TYPE=T (CLOSE macro) 36-38 
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u 



U-format records, specifying 
BDAM 51 
BPAM 62 
BSAM 80 
QSAM 106 
UCS feature 

unblocking data checks 78, 105 
UCS operand (SETPRT macro) 1 57 
unblocking data checks 
BSAM 78 
QSAM 105 
SETPRT macro 157 
uncorrectable I/O errors 
(see SYNAD operand) 
undefined length records 
(see U-format records) 
universal character set 
(see UCS operand) 
unmovable data sets 

(see DSORG operand) 
UPDAT open option 1 24 

restriction with POINT macro 131 
restriction with READ macro 144 
updating partitioned data set directory 1 66-1 67 
user 

data in partitioned data set directory 
BLDL macro 21-22 
STOW macro 166-167 
label exit 
BSAM 75 
list format 201 
QSAM 102 
totaling exit 
BSAM 75 
list format 201 
QSAM 102 
USING statement requirement 
DCBD macro 108-109 
PDABD macro 130 



V-format records, specifying 

BDAM 51 

BPAM 62 

BSAM 80 

QISAM 88 

QSAM 106 
validity checking, write 

BDAM 50 

BPAM 62 

BSAM 78 

QISAM 88 

QSAM 105 



variable-length, spanned records 

(see also V-format records) 

using BFTEK 45-46,66-67,93 

using BUILDRCD macro 26 

using PUT macro 136 

writing for BDAM 182 

restriction with 

FEOV macro 111 
GET macro 117 
OPTCD operand 78,105 
variable-length records 

(see V-format records) 
volume, forcing end of 111 
volume positioning 

CHECK macro 30 

CLOSE macro 36-38 

FEOV macro 111 

OPEN macro 123-126 

POINT macro 131-132 
volume switching 30, 1 1 1 

w 

WAIT macro instruction 

description 175-176 

relationship to 

CHECK macro 30 
MACRF operand 49 
READ macro 139,142 
WRITE macro 177,179 

use by access method 197 
work area for BISAM 

address of 56 

size of 56 
WRITE macro instruction 

execute form 186 

list form 185 

relationship to 

BUFL operand 47 
CHECK macro 30 
KEYLEN operand 48 
LIMCT operand 48-49 
MACRF operand 49,54,61,77 
NCP operand 55,61,77 
OPTCD operand 50 
POINT macro 131 
PRTOV macro 133 
READ macro 139,142,144 
RELEX macro 149 
SYNAD AF macro 169 
WAIT macro 175 

return codes 184 

specified in DCB macro 
BDAM 49-50 
BISAM 54-55 
BPAM 61 
BSAM 77-75 
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standard form 

BD AM (create with BSAM) 1 82-1 84 

BDAM (existing) 177-178 

BISAM 179-180 

BPAM 181 

BSAM 181 
testing for completion 30,175-176 
use by access method 197 
WTOR macro, relationship with SETPRT macro 155 



XCTL macro, relationship with BLDL macro 21 
XLATE macro instruction 187 
use by access method 197 
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